Creating Reference Maps for Message Types

When you create a new Source at Host or Receive from Partners message type with a CSV, JSON, or XML format, you must associate the message type with a DataWeave reference map. This is optional for Receive from Partners message types with an EDFIACT or X12 format. Reference maps can include custom message attributes that are extracted from the message payloads at runtime. The extracted attributes are visible in the payload and are available for searching and tracking.

If the definition for the message type includes an uploaded schema, the input of the reference map is the payload that follows the schema.

The output of the reference map contains the following fields:

Field

Description

Required or Optional

partnerReferenceId

Identifier that uniquely identifies the partner

Required for:

All Source at Host message types
Receive from Partners message types with a CSV. JSON, or XML format

You can hardcode this value as a static value, depending on your data processing and routing needs.

hostReferenceId

Identifier that uniquely identifies the host

Required for:
- Receive from Partners message types with a CSV, JSON, or XML format
Optional for:
- Receive from Partners message types formatted with an EDIFACT or X12 format
- All Source at Host message types

You can hardcode this value as a static value, depending on your data processing and routing needs.

The JSON schema allows hostReferenceId to be null because it’s shared across message types. For Receive from Partners message types that use JSON, CSV, or XML, hostReferenceId is still required.

businessDocumentKey.

Key reference value, such as Order Number or Invoice number

Optional

customAttributes

Array of custom message attributes to extract from the payload. You can specify up to 100 custom message attributes in a given environment and can make up to 25 of them searchable.

When specifying a custom message attribute, configure the following fields in the reference map:

alias

Alias that uniquely identifies a pre-configured custom message attribute configuration. The aliases in the reference map must match the message type’s attribute definitions. If the map contains aliases that don’t exist, creating or updating the message type fails.
values

An array of values, such as order numbers or invoice numbers.

Use an array of strings, even if there is only one attribute to extract. Using an array enables support for transactions with one-to-many relationships, such as transactions in which one shipment notice includes multiple purchase order numbers.

Optional

The output of a reference map must conform to this validation schema:

%dw 2.0
output application/json
---

{
	"definitions": {},
	"$schema": "http://json-schema.org/draft-07/schema#",
	"title": "Root",
	"type": "object",

	"properties": {
		"partnerReferenceId": {
			"type": "string",
			"default": "",
			"pattern": "^.*$"
		},
		"hostReferenceId": {
			"type": ["string", "null"],
			"default": "",
			"pattern": "^.*$"
		},
		"businessDocumentKey": {
			"type": ["string", "null"],
			"default": "",
			"pattern": "^.*$"
		},
		"customAttributes": {
			"type": "array",
			"default": [],
			"items":{
				"type": "object",
				"required": [
					"alias",
					"values"
				],
				"properties": {
					"alias": {
						"type": "string",
						"default": "",
						"pattern": "^.*$"
					},
					"values": {
						"type": "array",
						"default": [],
						"items":{
							"type": "string",
							"default": "",
							"pattern": "^.*$"
						}
					}
				}
			}

		}
	}
}

If the output of a reference map does not conform to the validation schema, the custom message attributes won’t appear in the Partner Manager GUI. To ensure that the output of a reference map conforms to the validation schema, you can add an Anypoint Connector for X12 EDI (X12 Connector) Validate schema operation to your MuleSoft app, as shown in these Exchange examples:

When you create a reference map, you can access other source message attributes in those maps. For information, see Accessing Source Message Attributes.

Example Map for a Receive from Partners Message Type

The following map transforms a partner’s inbound X12 payload. The map contains a business document key and two custom message attributes:

The value of the business document key is payload.TransactionSets.v004010."855".Heading."020_BAK".BAK03[0].
The value of the purchaseOrderNumber custom message attribute is payload.TransactionSets.v004010."855".Heading."020_BAK".BAK03[0].
The value of the vendorSalesOrderNumber custom message attribute is payload.TransactionSets.v004010."855".Heading."020_BAK".BAK08[0].

The input to the map looks like this:

%dw 2.0
output application/json
{
	businessDocumentKey: payload.TransactionSets.v004010."855".Heading."020_BAK".BAK03[0] default "",
	customAttributes: [
		{
			alias: "purchaseOrderNumber",
			values: [payload.TransactionSets.v004010."855".Heading."020_BAK".BAK03[0]]
		},
		{
			alias: "vendorSalesOrderNumber",
			values: [payload.TransactionSets.v004010."855".Heading."020_BAK".BAK08[0]]
		}
	]
}

The generated output of the map looks like this:

{
  "businessDocumentKey": "ORDER-70010",
  "customAttributes": [
    {
      "alias": "purchaseOrderNumber",
      "values": [
        "ORDER-70010"
      ]
    },
    {
      "alias": "vendorSalesOrderNumber",
      "values": [
        "SO-5100803142"
      ]
    }
  ]
}

Example Map for a Source at Host Message Type

The following map transforms the outbound JSON or XML payload from the backend. The map contains the partner reference ID, host reference Id, business document key, and three custom attributes:

The value of the partner reference ID is payload.Header.CustomerName.
The value of the host reference ID is payload.Invoice.Header.LineOfBusiness.
The value of the business document key is payload.Invoice.Header.InvoiceNumber.
The value of the invoiceNumber custom attribute is payload.Invoice.Header.InvoiceNumber.
The value of the purchaseOrderNumber custom message attribute is payload.Invoice.Header.PurchaseOrderNumber.
The value of the invoiceAmount custom message attribute is payload.Invoice.Header.TotalInvoiceAmt.

The input to the map looks like this:

%dw 2.0
output application/json
---
{
	partnerReferenceId: payload.Invoice.Header.CustomerName,
	hostReferenceId: payload.Invoice.Header.LineOfBusiness default "MYTHICAL",
	businessDocumentKey: payload.Invoice.Header.InvoiceNumber,
	customAttributes: [
		{
			alias: "invoiceNumber",
			values: [payload.Invoice.Header.InvoiceNumber default "UNKNOWN"]
	},
	{
			alias: "purchaseOrderNumber",
			values: [payload.Invoice.Header.PurchaseOrderNumber default "UNKNOWN"]
	},
	{
			alias: "invoiceAmount",
			values: [ "\$ " ++ payload.Invoice.Header.TotalInvoiceAmt default "UNKNOWN"]
	}
]
}

The generated output of the map looks like this:

{
  "partnerReferenceId": "ALPHA-CAN",
  "hostReferenceId": "Mythical-MG",
  "businessDocumentKey": "INV97750061",
  "customAttributes": [
    {
      "alias": "invoiceNumber",
      "values": [
        "INV97750061"
      ]
    },
    {
      "alias": "purchaseOrderNumber",
      "values": [
        "ORD3893988"
      ]
    },
    {
      "alias": "invoiceAmount",
      "values": [
        "$ 3756.24"
      ]
    }
  ]
}

Exchange Examples of DataWeave Maps

For examples of DataWeave maps on Exchange that include custom message attributes, see:

Creating Reference Maps for Message Types

Example Map for a Receive from Partners Message Type

Example Map for a Source at Host Message Type

Exchange Examples of DataWeave Maps

See Also