---
category: [Administration & Integrations, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions, Platform and Product Extensions/Workday Extend, Platform and Product Extensions/Integration]
keyword: [Extend, Orchestration Builder, Orchestrate, Orchestration]
nav: wcp_docs
parent_url: /wcp_docs/
title: >- 
  Concept: Character Mapping
layout: subsection
---

Workday Orchestrate's character mapping functionality can help you overcome the challenges of processing text data in accordance with specific character set requirements. It enables you to transform text data by defining how each element in a source character set map to an equivalent in a target character set.

Specifically, you can:

-   Map non-UTF8 or special characters to their UTF8 equivalents.
-   Define custom replacement strategies for characters that don't have a direct equivalent in the target character set.
-   Exclude characters that aren't permissible in or relevant to the target character set.


You can create character mappings within an orchestration or import them in a CSV file. Once you've defined the mappings, you can apply them to specific sections of text or to entire documents.

## <a id="section_1"></a>Mapping Functions

Orchestration Builder provides 2 functions for creating character mappings:

<table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td>createCharacterReplacementMapping</td><td>Arguments: <ul><li>csv (CsvType)
</li></ul> Return type: <ul><li>StringMap
</li></ul> Uses the provided CSV file to return a mapping for character replacement in documents or strings. The CSV file should have 2 columns, representing key and replacement value. The key is a single character. The value can be 1 or more characters.</td></tr><tr><td>createCharacterReplacementMapping</td><td>Arguments: <ul><li>csv (CsvType)
</li><li>upsertMapping (StringMap)
</li></ul> Return type: <ul><li>StringMap
</li></ul> Uses the provided CSV file and string map to return a mapping for character replacement in documents or strings. The CSV file should have 2 columns, representing key and replacement value. The key is a single character. The value can be 1 or more characters. The string map values supersede the CSV values.</td></tr><tr><td>createCharacterInclusionList</td><td>Arguments: <ul><li>csv (CsvType)
</li></ul> Return type: <p>StringList</p> Uses the provided CSV file to return a list of characters for inclusion, excluding all others. The CSV file should have 1 column containing single characters.</td></tr><tr><td>createCharacterInclusionList</td><td>Arguments: <ul><li>csv (CsvType)
</li><li>additionalList (StringList)
</li></ul> Return type: <ul><li>StringList
</li></ul> Uses the provided CSV file and string list to return a list of characters for inclusion, excluding all others. The CSV file should have 1 column containing single characters. Its contents and the contents of the string list are combined to create the inclusion list.</td></tr></tbody></table><br/>

There are 3 functions for character replacement, each of which can be applied to the CSV, JSON, XML, Text or String types, returning data in those same types:

<table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td>replaceCharactersUsingMapping</td><td>Arguments: <ul><li>mapping (StringMapType)
</li></ul> Return types: <ul><li>Csv, Json, Xml, Text, String
</li></ul> Returns a document or string with characters replaced according to the provided mapping. If a character isn't mapped, it's returned unchanged.</td></tr><tr><td>replaceAndIncludeCharacters</td><td>Arguments: <ul><li>mapping (StringMapType)
</li><li>defaultReplacement (StringType)
</li></ul> Return type: <ul><li>Csv, Json, Xml, Text, String
</li></ul> Returns a document or string with characters replaced according to the provided mapping. If a character is missing from the provided document or string, the default string is returned.</td></tr><tr><td>includeCharactersUsingList</td><td>Arguments: <ul><li>inclusionList (StringListType)
</li><li>defaultReplacement (StringType)
</li></ul> Return type: <ul><li>Csv, Json, Xml, Text, String
</li></ul> Returns a document or string replacing any characters not present in the inclusion list with the specified replacement. Characters that are on the inclusion list are returned unchanged, as are CSV or JSON control characters.</td></tr></tbody></table><br/>

## <a id="section_2"></a>Example Scenario: Replacing Accented Characters

Orchestration Builder enables you to define a mapping that replaces characters like é with e and ö with o, ensuring consistency and compatibility across systems.

Suppose you're dealing with this JSON data containing accented characters that you want to replace with their closest non-accented equivalents:

```
{
 "workers": [
   {
     "name": "Jürgen Müller",
     "email": "jürgen.müller@company.com"
   },
   {
     "name": "Ana María López",
     "email": "ana.maría.lopez@company.com"
   }
 ]
}
```

Create a mapping CSV containing these values:

```

æ,ae

Ø,Oe

Å,Aa

å,aa

ö,oe

ü,u
```

Use the `createCharacterReplacementMapping` function to refer to the CSV:

```
characterMappings = mapping.createCharacterReplacementMapping(inputMappingCSV)
```

Use the `replaceCharactersUsingMapping` function to perform the replacements:

```
modifiedJson = replaceCharactersUsingMapping(characterMappings)
```

Here's how that might look in the Orchestrate <b>Create Text Template</b> component:

```
<workers>
 {{#each data.input.json.iterator("$.workers.[*]")}}
   <worker>
     <name>{{this.stringAtJsonPath("$.name").replaceCharactersUsingMapping(characterMappings)}}</name>
     <email>{{this.stringAtJsonPath("$.email").replaceCharactersUsingMapping(characterMappings)}}</email>
   </worker>
 {{/each}}
</workers>
```

This is the XML output, following character replacement:

```
<workers>
 <worker>
   <name>Juergen Mueller</name>
   <email>juergen.mueller@company.com</email>
 </worker>
 <worker>
   <name>Ana Maria Lopez</name>
   <email>ana.maria.lopez@company.com</email>
 </worker>
</workers>
```

## <a id="section_3"></a>Example Scenario: Excluding Unsupported Characters

Orchestration Builder enables you to define a character mapping that excludes certain characters.

Suppose you're dealing with this JSON data containing non-ASCII characters and need to provide a file containing ASCII characters only:

```
 [
   {
     "name": "Øistein",
     "age": 24
   },
   {
     "name": "Øivind",
     "age": 35
   }
 ]
```

Create an inclusion list of type `StringList`, like so:

```
[a, b, c, ..., z, A, B, C, ..., Z, 0, 1, 2, ..., 9, !, ?, ., ...]
```

Use the `createCharacterInclusionList` function to refer to the inclusion list:

```
inclusionList = mapping.createCharacterInclusionList(csv)
```

Use the `includeCharactersUsingList` function to remove non-ASCII characters:

```
modifiedJson = json.includeCharactersUsingList(inclusionList, "")
```

Here's how that might look in the Orchestrate <b>Create Text Template</b> component:

```
[
   {{#each data.input.json.iterator(“$.*”) as worker}}  
   {
     "name": "{{item.worker.stringAtJsonPath(“$.name”).includeCharactersUsingList(inclusionList, “”)}}",
     "age": {{item.worker.numberAtJsonPath(“$.age”)}}
   }
   {{#if !item.worker.isLast}} , {{/if}}  
   {{/each}}
 ]
```

This is the JSON output, following character replacement:

```
[
   {
     "name": "istein",
     "age": 24
   },
   {
     "name": "ivind",
     "age": 35
   }
```

## <a id="section_4"></a>Example Scenario: Custom Character Replacement

Orchestration Builder enables you to define a character mapping that contains custom replacements.

Suppose you want to replace the @ and # characters in this text with the text [at] and [hash], respectively:

```
Original text with @ and # symbols
```

Use the `createCharacterReplacementMapping` function to define the custom replacements:

```
customMapping = createCharacterReplacementMapping(csv, Map("@" -> "[at]", "#" -> "[hash]"))
```

Use the `replaceCharactersUsingMapping` function to perform the replacements:

```
modifiedText = text.replaceCharactersUsingMapping(customMapping)
```

This is the output text, following character replacement:

```
Original text with [at] and [hash] symbols
```

## <a id="section_5"></a>Example Scenario: Custom Character Mapping and Filtering

Orchestration Builder enables you to map specific characters to other characters and to replace any not included in the mapping with a default placeholder.

Suppose you're dealing with this input XML:

```
<people>
  <person>HæRRY</person>
  <person>Østwald</person>
  <person>Åbcdåb</person>
  <person>Øistein</person>
  <person>Øivind</person>
  <person>Ømer</person>
</people>
```

Create a mapping CSV containing these values:

```

æ,ae
Å,Aa
p,p
e,e
o,o
l,l
r,r
s,s
o,o
n,n
```

Use the `createCharacterReplacementMapping` function to refer to the CSV:

```
mappingDef = mapping.createCharacterReplacementMapping(mappingCSV)
```

Use the `replaceCharactersUsingMapping` function to filter out characters not mentioned in the mapping and replace them with a ~ symbol:

```
outputDocument = xml.replaceCharactersUsingMapping(mappingDef, “~”)
```

Here's how that might look in the Orchestrate <b>Create Text Template</b> component:

```
<people>
 {{#each data.input.xml.iterator("/people/*")}}
   <person>{{this.stringAtXPath("/name").replaceAndIncludeCharacters(mappingDef, “~”)}}</person>
 {{/each}}
</people>
```

This is the output text, following character replacement and filtering:

```
<people>
  <person>~ae~~~</person>
  <person>~s~~~l~</person>
  <person>Aa~~~~~</person>
  <person>~~s~e~n</person>
  <person>~~~~n~</person>
  <person>~~er</person>
</people>
```

### Related Information

[Reference: Mapping Global Functions](/wcp_docs/GUID-8f0ee7b0-1cbd-44a8-9401-949e429160e8-enHYPHENus.html)

[Reference: Csv Member Functions](/wcp_docs/ptu1641383088921.html)

[Reference: Json Member Functions](/wcp_docs/vsl1598549308984.html)

[Reference: Xml Member Functions](/wcp_docs/vog1598549366757.html)

[Reference: Text Member Functions](/wcp_docs/iem1658831408198.html)

[Reference: String Member Functions](/wcp_docs/rbo1597335964354.html)