# Advanced Mapping Utility

## Overview

* This Advance Utility is useful when user want some customization in default xslt or user have some specific requirement. For acheiving those requirement <code class="expression">space.vars.SITENAME</code> provides some Utilities which handle some custom requirement.

## Common placeholder and its value

|  **Placeholder**  |              **Value**             | **Description**                                                                                                                                                                                             |
| :---------------: | :--------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<<Workflow Id>>` |             $workflowId            | if workflowId is required for any utility pass it as $workflowId, it is always available in mapping xml.                                                                                                    |
|  `<<System Id>>`  | $sourceSystemId or $targetSystemId | If the requirement is to have the value for the source system then set this as '$sourceSystemId' and if the requirement is to have the value for the target system then set the value as '$targetSystemId'. |

## Utilities

### Get Field Value of Entity

* **Overview:** This Utility will help to fetch value of any field of specific entity.
* **Utility Definition:**

  ```code
  getEntityFieldValue(WorkflowId, SystemId, ProjectValue, EntityType, EntityId, FieldInternalName)
  ```
* This utility can be used in the advance xslt in this manner:

  ```xml
  <xsl:value-of select="utils:getEntityFieldValue(<<Workflow Id>>,<<System Id>>,<<Project Value>>,<<Entity Internal Name>>,<<Entity Id>>,<<Internal Field Name>>)"/>
  ```

*How to set the placeholders:*

* `<Workflow Id>`: refer [Common placeholder and its value](#common-placeholder-and-its-value) section.
* `<System Id>`: refer [Common placeholder and its value](#common-placeholder-and-its-value) section.
* `<Project Value>`: Pass project's value if required else pass null.
* `<Entity Internal Name>`: Pass internal name for the entity.
* `<Entity Id>`: Pass internal id of specific entity for fetching particular field's value.
* `<Internal Field Name>`: Pass field's internal name for fetching value of it.

***

### Get Matching Lookup Value of Target from Source

* **Overview:** This Utility will help to find matching lookup value from system by giving regular expression.
* **Utility Definition:**

  ```
  getMatchingLookupValue(WorkflowId, SystemId, projectValue, EntityType, RegexExpression, isRegexOnInternalValue, isThrowErrorOnMultipleMatch, isRefreshOnCacheMiss)
  ```
* This utility can be used in advance xslt in this manner:

```xml
<xsl:value-of select="utils:getMatchingLookupValue(<<Workflow Id>>,$targetSystemId,<<Project Value>>,<<Internal Field Name>>,<<RegexExpression>>,<<Regex on Internal Value>>,<<Throw Error On Multiple Match>>,<<Refresh On Cache Missing>>)"/>
```

*How to set the placeholders:*

* `<<Workflow Id>>`: refer [Common placeholder and its value](#common-placeholder-and-its-value) section.
* `<<Project Value>>`: Pass project's value if required else pass null.
* `<<Internal Field Name>>`: Pass field's internal name for fetching value of it.
* `<<RegexExpression>>`: Here, the user can pass a valid regular expression. If user wants to map the lookup values in such a way that it fetches the value which ends with field value of source entity, then pass `concat('.*','<<Searched value>>')`.
* `<<Regex On Internal Value>>`: Pass this as `'true'`, if user wants to search value on basis of internal value of lookup, else pass `'false'` which will search on the basis of display value of lookup.
* `<<Throw Error On Multiple Match>>`: Pass this as `'true'`, if user wants to throw error if multiple match are found for given expression, else pass `'false'` which will throw error in case there are multiple lookups with the same value found.
* `<<Refresh On Cache Miss>>`: <code class="expression">space.vars.SITENAME</code> maintains cache for lookups to decrease the number of times API is called for the end system. If the user passes the value as `'true'`, <code class="expression">space.vars.SITENAME</code> will reload the cache if a lookup with a certain value is not found. If this is passed as `'false'`, <code class="expression">space.vars.SITENAME</code> will always refer the cache and will not reload the cache if a certain matching lookup is not found.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://opstech.gitbook.io/opstech-docs/7.223/integrate/configure-integrations/mapping-configuration/advance-mapping-utility.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.