Field Maps in Nama ERP - Complete Guide (AI-Generated by Claude.ai)

Overview

Field maps are a powerful feature in Nama ERP that allow automatic copying and transformation of data between different entities (records). This system is primarily used in Entity Flows to generate new documents from existing ones (e.g., creating a Credit Note from a Sales Invoice).

Basic Concept

A field map is a set of instructions that tells the system:

What data to copy (source field)
Where to copy it (target field)
How to transform it (optional functions)

The basic syntax is:

targetField=sourceField

Simple Field Mapping

Direct Field Copy

The simplest form copies a value from one field to another:

code=code                  # Copy code from source to target
description=description    # Copy description from source to target
customer=customer          # Copy customer reference from source to target

Setting Fixed Values

You can set fields to specific values:

status="Active"           # Set status to the text "Active"
priority=1                # Set priority to number 1
isApproved=true          # Set boolean value
discount=null            # Clear the field

Downloading Files from URLs (Attachments)

For attachment fields (LargeData type), you can provide a URL and the system will automatically download the file:

# Direct URL - downloads and stores the file
attachment="https://example.com/files/sample.pdf"

# URL from another field
attachment2=productImageURL

# Download contract document from customer website
contractFile=customer.contractDocumentURL

# Download image from product catalog
productImage=item.imageURL

How URL Download Works

When you set an attachment field to a URL (any string containing ://), the system:

Detects it's a URL and initiates an HTTP GET request
Downloads the file content from the URL
Extracts the filename from the Content-Disposition header or URL path
Stores the file data in the LargeData field
If the field already has an attachment, it updates it instead of creating a new one

URL Requirements

URLs must be accessible via HTTP/HTTPS
No authentication is performed (URL must be publicly accessible or include auth tokens in the URL)
Failed downloads are logged but won't stop the field map execution
Large files may impact performance - use cautiously

Special References

ref5=$this               # Set ref5 to reference the source entity itself
fromDocument=$this       # Create a link back to the source document

Working with Collections (Detail Lines)

Copying Entire Tables

When documents have detail lines (like invoice items), you can:

details=[lines]          # Create same number of lines as source
details=[5]              # Create exactly 5 empty lines
details=[clear]          # Remove all existing lines

Adding Lines

details=[addLines(5)]              # Add 5 new empty lines
details=[addLines(lines)]          # Add same number as source lines
details1=[addLines(details2)]      # Add lines based on another collection

Copying Field Values to All Lines

details.warehouse=warehouse        # Copy header warehouse to all detail lines
details.project=project           # Copy header project to all detail lines

Line-by-Line Copying

details.quantity=lines.quantity    # Copy quantity from each source line
details.price=lines.unitPrice      # Copy price from corresponding lines
details.item=lines.item           # Copy item references

Advanced Functions

Text Manipulation

Masking

Format text according to a pattern:

altCode=mask(code,XXX-XXX-XXX)    # ABC123456 becomes ABC-123-456
phoneDisplay=mask(phone,XXXX XXX XXXX)  # 0501234567 becomes 0501 234 567
details.text1=mask(details.text2,XX-XX:X--X)  # Works on detail lines too

X represents a character from the original value
Any other character (like -, ., :, *, @) is inserted as-is

Examples:

If item code is 111222333 and you use mask(code,XXX-XXX*XXX), the result is 111-222*333
If item code is ABC155713 and you use mask(code,XXX-XXX@XXX), the result is ABC-155@713

Text Extraction

firstFive=description.$left_5      # Get first 5 characters
lastTwo=code.$right_2             # Get last 2 characters
middle=ref1.$mid_3_4              # Get 4 characters starting at position 3

Mathematical Functions

Totaling Values

Calculate sum of values in detail lines:

totalAmount=totalize(details,details.price)
netTotal=totalize(lines,lines.netAmount)
n1=totalize(details,details.price.unitPrice)

Conditional Totaling

Sum values only when a condition is met:

serviceTotal=totalizeif(details,details.price,select case when {details.item.item.itemType} = 'Service' then 1 else 0 end)
n1=totalizeif(details,details.price.unitPrice,select case when {details.item.item.section.code} = 'SEC001' then 1 else 0 end)

Min/Max Functions

Get the minimum or maximum value from detail lines:

n1=max(details.price.unitPrice)    # Get the maximum unit price
n1=min(details.price.unitPrice)    # Get the minimum unit price

SQL-Based Calculations

For complex calculations across detail lines:

# Sum of calculated values
weightedTotal=totalizesql(select {details.quantity} * {details.unitPrice} * {details.discount} / 100)
n1=totalizesql(select {details.price.unitPrice} * {details.n1} / {n3})

# Maximum of calculated values
n1=maxsql(select {details.price.unitPrice} * {details.n1} / {n3})

# Minimum of calculated values
n1=minsql(select {details.price.unitPrice} * {details.n1} / {n3})

Database Queries

Simple SQL Queries

customerBalance=sql(select balance from Customer where id = {customer.id})
lastInvoiceDate=sql(select max(valueDate) from SalesInvoice where customer_id = {customer.id})
n1=sql(select sum(netValue) from SalesInvoice where customer_id = {customer.id})

Multi-line SQL

For complex queries that span multiple lines:

complexValue=mlsql(
  select case
    when {totalAmount} > 1000 then 'High'
    when {totalAmount} > 500 then 'Medium'
    else 'Low'
  end
)endmlsql

# Another example with case statement
n1=mlsql(select case when {code} = 'abc' then 5 when {code} = 'cde' then 6 else 7 end)endmlsql

Detail SQL Fields

To access SQL-computed fields (sqlField1, sqlField2, etc.) in detail collections, you must first enable them:

enableDetailSqlFields="details"
details.n1=details.sqlField1
details.n2=details.sqlField2

Performance Consideration

Using detail SQL fields can significantly impact performance because the SQL statements are executed per line. For entities with many detail lines, this can result in slow processing. Use this feature sparingly and consider alternative approaches like totalizesql for aggregate calculations when possible.

Advanced SQL Parameter Syntax

When writing SQL queries with parameters, Nama ERP provides several advanced parameter syntaxes for common patterns:

Literal Substitution (`{!paramName}`)

Use {!paramName} to substitute a parameter value directly into the SQL statement (not as a prepared statement parameter). This is useful for dynamic table or column names:

-- Dynamic table name
select count(*) from {!tableName} where status = 'Active'

-- Dynamic column selection
select {!columnName} from Customer where id = {customer.id}

Security Note

Literal substitution inserts values directly into the SQL. Only use with trusted, controlled values - never with user input, as this could lead to SQL injection.

IN Clause with Empty List Support (`{xIN,column,paramName}`)

Use {xIN,column,paramName} for IN clauses that gracefully handle empty collections:

/*
 If customerIds is empty: produces "1 = 1" (always true)
 If customerIds has values: produces "customer_id in (?,?,?)"
*/
select count(*) from SalesInvoice where {xIN,customer_id,customerIds}

-- Combined with other conditions
select sum(netValue) from SalesInvoice where status = 'Posted' and {xIN,customer_id,selectedCustomers}

`customerIds` Value	Generated SQL
`null` or empty list	`... where 1 = 1`
`[1, 2, 3]`	`... where customer_id in (?,?,?)`
Single value `5`	`... where customer_id in (?)`

Between with Null Support (`{xBetween,column,fromParam,toParam}`)

Use {xBetween,column,fromParam,toParam} for range queries where either bound might be empty. Use brackets [ and ] to include the boundary values (>= and <=), or omit them for exclusive comparison (> and <):

-- Inclusive range: code >= ? and code <= ?
select count(*) from Customer where {[xBetween],code,fromCode,toCode}

-- Exclusive range: code > ? and code < ?
select count(*) from Customer where {xBetween,code,fromCode,toCode}

-- Left-inclusive only: code >= ? and code < ?
select count(*) from Customer where {[xBetween,code,fromCode,toCode}

-- Right-inclusive only: code > ? and code <= ?
select count(*) from Customer where {xBetween],code,fromCode,toCode}

`fromCode`	`toCode`	Generated SQL (inclusive `[xBetween]`)
`"A"`	`"Z"`	`code >= ? and code <= ?`
`"A"`	`null`	`code >= ?`
`null`	`"Z"`	`code <= ?`
`null`	`null`	`1 = 1`

Conditional Comparison Operators (`{xOP,column,paramName}`)

Use {xOP,column,paramName} where OP is a comparison operator (=, <>, >, >=, <, <=). If the parameter is null, the condition is replaced with 1 = 1:

/*
If minAmount is null: produces "1 = 1"
If minAmount has value: produces "amount >= ?"
*/

select count(*) from SalesInvoice where {x>=,amount,minAmount}

-- Multiple conditional comparisons
select count(*) from SalesInvoice where {x=,status,filterStatus} and {x>=,valueDate,fromDate} and {x<=,valueDate,toDate}

Syntax	Parameter Value	Generated SQL
`{x=,code,customerCode}`	`"ABC"`	`code=?`
`{x=,code,customerCode}`	`null`	`1 = 1`
`{x<>,status,excludeStatus}`	`"Draft"`	`status<>?`
`{x>=,amount,minAmount}`	`100`	`amount>=?`

Conditional Value Selection

First Not Empty

Returns the first value that is not empty:

details.ref1=firstNotEmpty(details.ref1,ref1,customer.ref1)
contactPhone=firstNotEmpty(customer.mobile,customer.phone,customer.contact.phone)
details.n1=firstNotEmpty(details.n5,netValue,n4)

Tips

You can use an unlimited number of fields inside firstNotEmpty.

First Not Null

Returns the first value that is not null:

details.project=firstNotNull(details.project,project,customer.defaultProject)

Multilingual Support

name() Function

Use the name() function to support multiple languages. It returns the first value (Arabic) in Arabic environments and the second value (English) in English environments:

description1=name(name1,name2)           # Uses field values
description2=name("Arabic Text","English Text")  # Uses literal strings

Reference Creation

Create references to other entities:

# Fixed reference by entity type and code
relatedInvoice=ref("SalesInvoice","SIV150160")

# Reference from a book code
book="BookCode"

# Reference from another field
term=book.code

# Reference to the current entity
ref5=$this

# Clear a reference
book=null

# Dynamic reference based on SQL
parentDoc=ref(ref2.entityType,sql(select id from SalesInvoice where code = {ref1}))
ref4=ref(ref2.$toReal.ref1.entityType,sql(select top 1 id from Customer where ref4id = {ref4.$toReal.id}))

Advanced Line Matching

Match Lines By Fields

Match source and target lines based on specific fields:

matchLinesBy=details.item.item=lines.ref1,details.warehouse=lines.warehouse(
  details.quantity=lines.quantity
  details.price=lines.unitPrice
  details.discount=lines.discount
)endMatchLinesBy

This will:

Match lines where item and warehouse are the same
Only copy data between matched lines
Ignore unmatched lines

Filter Lines

Process only specific lines based on conditions:

filterLinesBy=(
  filterSourceDetail=details
  filterSourceBy=sql(select case when {details.quantity} > 0 then 1 else 0 end)
  filterTargetDetail=lines
  filterTargetBy=sql(select case when {lines.item.item.isActive} = 1 then 1 else 0 end)

  # Copy only between filtered lines
  lines.quantity=details.quantity
)endFilterLinesBy

You can filter source only, target only, or both.

Filter with Keyword Lines

You can also filter lines and copy them to a keyword collection:

filterLinesBy=(
  filterSourceDetail=creditLimits
  filterSourceBy=sql(select case when {creditLimits.paymentPeriod} > 5 then 1 else 0 end)
  keywordLines=[creditLimits]
  keywordLines.keyword=creditLimits.paymentPeriod
)endFilterLinesBy

Tips

You can use a numeric field from the line instead of an SQL statement. In this case, lines where this field has a non-zero value will be included.

Tempo Expression Integration

Single-Line Tempo Expressions

Field maps support embedded Tempo expressions for dynamic text generation and complex field calculations:

# Basic tempo field reference
customerInfo=tempo(Customer {customer.name1} has code {customer.code})

# Format with date functions
processedInfo=tempo(Processed by {$user.name2} on {$today})

# Conditional content
statusMessage=tempo({if(status)}Active since {valueDate}{else}Not active{endif})

# Links and hyperlinks
customerLink=tempo({link(customer)})

# Calculations and totals
summaryText=tempo(Total amount: {money.netValue}, Customer: {customer.name1})

Multi-Line Tempo Expressions

For complex tempo templates with multiple lines, loops, or detailed formatting:

# Complex customer summary
customerSummary=mltempo(
Customer Details:
- Name: {customer.name1}
- Code: {customer.code}
- Balance: {customer.n1}
)endmltempo

# Invoice details with table
invoiceDetails=mltempo(
Invoice Summary for {customer.name1}

{opentable}
{row}{cell}Item{cell}Quantity{cell}Price{cell}Total{endrow}
{loop(details)}
  {row}
    {cell}{details.item.item.name1}
    {cell}{details.quantity.quantity.primeQty.value}
    {cell}{details.price.unitPrice}
    {cell}{details.price.netValue}
  {endrow}
{endloop}
{closetable}

Total Amount: {money.netValue}
)endmltempo

# Conditional content with complex logic
approvalMessage=mltempo(
{if(currentApprovalCase.state)}
  {if=(currentApprovalCase.state,"Approved")}
    ✅ Approved by {currentApprovalCase.lastStep.actualResponsible.name1} on {currentApprovalCase.currentApprovalCase.completionDate}
    {if(currentApprovalCase.lastStep.approvalComment)}
      Comment: {currentApprovalCase.lastStep.approvalComment}
    {endif}
  {else}
    ❌ Status: {translate(currentApprovalCase.state)}
  {endif}
{else}
  ⏳ Pending approval
{endif}
)endmltempo

Special Operations

Switch Target/Source

When working with collections (detail lines) in referenced entities, you need to use special syntax to properly access and modify fields.

Working with Header Fields in Referenced Entities

For header fields in referenced entities, you can use direct dot notation:

# This works - modifying a header field in customer
customer.n1="5"

The Problem with Collections in Referenced Entities

However, when you need to work with collections (details) inside referenced entities, the simple dot notation doesn't work:

# ❌ This will NOT work as expected
customer.lines.n1=n1

This is where switchTarget and switchSource become essential.

Using switchTarget - Modifying Collections in Referenced Entities

Use switchTarget when you need to modify fields in collections within a referenced entity:

# ✅ Correct way to modify collections in customer object
switchTarget=customer(
  lines.n1=n1
)endSwitchTarget

Tips

Notice that inside switchTarget, we omit the customer. prefix because we're already working inside the customer context.

More Examples:

# Update related document details
switchTarget=relatedDocument(
  # Now copying TO each related document's collections
  status="Processed"
  processedBy=currentUser
  processedDate=sql(select getdate())

  # Working with collections inside the related document
  details.processed=true
  details.processedDate=sql(select getdate())
)endSwitchTarget

Using switchSource - Copying from Collections in Referenced Entities

Use switchSource when you need to copy data FROM collections within a referenced entity TO collections in the current entity:

# ❌ This will NOT work as expected
details.n1=customer.lines.n1

# ✅ Correct way to copy from customer collections to invoice collections
switchSource=customer(
  details.n1=lines.n1
  details.item=lines.item
  details.quantity=lines.quantity
)endSwitchSource

Tips

Inside switchSource, the left side (target) refers to the current entity's collections, and the right side (source) refers to the referenced entity's collections without the prefix.

More Examples:

# Copy data from a nested reference
switchSource=customer.ref1(
  totalPurchases=n5  # n5 here will come from customer.ref1
  lastOrderDate=date1
)endSwitchSource

# Copy from supplier collections to purchase order
switchSource=supplier(
  details.defaultPrice=priceList.price
  details.leadTime=priceList.deliveryDays
)endSwitchSource

Working with Generic References ($toReal)

When working with generic reference fields (like fromDoc which can point to different entity types), you normally need to use $toReal to access the actual entity. However, switchSource and switchTarget handle this automatically:

# ❌ This will NOT work as expected
details=fromDoc.$toReal.details
details.text1=fromDoc.$toReal.details.description

# ✅ Correct way - $toReal is handled automatically
switchSource=fromDoc(
  details=[details]
  details.text1=details.description
)endSwitchSource

Tips

Notice that we do not need $toReal inside switchSource and switchTarget. Generic references are automatically resolved to their real entity type within the switch context.

Why this works:

Outside the switch: fromDoc is a generic reference that needs $toReal to access actual data
Inside the switch: The system automatically resolves fromDoc to its real entity type
You can directly access collections and fields without the $toReal operator

When to Use Each

Scenario	Syntax
Modify header field in referenced entity	`customer.n1="5"`
Modify collection in referenced entity	`switchTarget=customer(lines.n1=n1)endSwitchTarget`
Copy from collection in referenced entity	`switchSource=customer(details.n1=lines.n1)endSwitchSource`

Applicability

These switchTarget and switchSource features work in:

Entity Flows (Business process automation)
GUI Post Actions (Field change handlers)

Warning

Always remember to use endSwitchTarget and endSwitchSource to close the switch block. Missing these will cause syntax errors.

Working with Newly Added Lines

details=[addLines(5)]
details=addedLinesOnly(details.item=defaultItem)
details=addedLinesOnly(details.quantity=1)
details=addedLinesOnly(details.price=defaultPrice)

Line Selection

selectLine="details(0)"     # Select first line (0-based index)
$line.quantity=10          # Set quantity of selected line
$line.n1="15"              # Set n1 of selected line

selectLine="details(2)"     # Select third line (index 2)
n3=currentLine.n3          # Read from selected line using currentLine
n3=$line.n3                # Alternative: read from selected line using $line
$line.price=sql(select {$line.quantity} * {$line.unitPrice})  # Calculate price

selectLine="details(last)"  # Select last line
$line.isLast=true

Entity Commands

runCommand="edit"                          # Start editing mode
runCommand="save"                          # Save the entity
runCommand="recommit"                      # Re-save/recommit the entity
runCommand="forcestable"                   # Force update without validation
runCommand="unforcestable"                 # Cancel force update mode
runCommand="flush"                         # Flush database changes
runCommand="guessPeriod"                   # Auto-detect accounting period (DocumentFile only)
runCommand="makeValueDateToday"            # Set value date to today (DocumentFile only)
runCommand="setCodeIfNeeded"               # Set code from book or group
runCommand="copyDimensionsFromBookOrGroup"     # Copy Dimensions (legal entity, branch, department, analysis set, and branch) from book or group
runCommand="systemUpdateCalculatedFields"  # Update all calculated fields
runCommand="regenledger"                   # Regenerate ledger entries (if applicable)
runCommand="runManualEntityFlow(EF005)"    # Run specific entity flow by code
runCommand="encryptPassword"               # Encrypt password field (NaMaUser only)
runCommand="doNotCheckQty"                 # Skip quantity checks (InvoiceWithStockEffect only)
runCommand="collectStockDocsIfEmpty"       # Collect stock documents (InvoiceWithStockEffect only)

Common Command Combinations

# Set value date to today and auto-detect accounting period
runCommand="guessPeriod"
valueDate=sql(select getdate())

Adding Discussions

You can add discussion entries to an entity:

addDiscussion="New Discussion added by entity flow"

# Update item from within invoice line
details.item.item.runCommand="edit"
details.item.item.lastSaleDate=valueDate
details.item.item.lastSalePrice=details.price
details.item.item.runCommand="save"

Security Features

Encryption/Decryption

Multiple encryption methods are available with different passwords:

# Encrypt sensitive data using different encryption keys
encryptedCode=code.$encrypt1              # Encryption method 1
encryptedSSN=customer.ssn.$encrypt2       # Encryption method 2
encryptedData=data.$encryptX              # Encryption method X

# Decrypt when needed (use matching decrypt method)
originalCode=encryptedCode.$decrypt1
originalSSN=encryptedSSN.$decrypt2
originalData=encryptedData.$decryptX

You can also use encrypted values in SQL queries:

ref1=sql(select entityType,id from SalesInvoice where code = {description1.$decrypt1})

Using in Reports (Groovy/JasperReports)

NamaRep.encrypt1($F{code})
NamaRep.decrypt1($F{description1})

OTP Generation

Generate numeric or alphanumeric OTP codes with lengths from 4 to 8 characters:

# Numeric OTP (digits only)
description1=$createNumericOTP4     # e.g., 1234
description2=$createNumericOTP5     # e.g., 12345
description3=$createNumericOTP6     # e.g., 123456
description4=$createNumericOTP7     # e.g., 1234567
description5=$createNumericOTP8     # e.g., 12345678

# Alphanumeric OTP (letters and digits)
description1=$createOTP4            # e.g., A1B2
description2=$createOTP5            # e.g., A1B2C
description3=$createOTP6            # e.g., A1B2C3
description4=$createOTP7            # e.g., A1B2C3D
description5=$createOTP8            # e.g., A1B2C3D4

This documentation was generated by Claude.ai based on analysis of the Nama ERP source code and system functionality.