Functions

Functions in Gigantics allow you to create custom JavaScript transformations that can be applied to your data during processing. This feature provides a powerful way to modify, anonymize, or generate new values for fields in your datasets based on complex logic that goes beyond simple masking or replacement rules.

Functions are particularly useful when you need to:

• Apply complex business logic to transform data
• Generate new values based on combinations of existing fields
• Implement custom anonymization techniques
• Format data in specific ways not covered by built-in transformations

Function Types

There are two main categories of functions available in Gigantics:

Internal Functions

Built-in functions that handle common data transformation tasks:

• mask: Apply masking patterns to different data types
• fake: Generate realistic fake data using the Faker library
• codeRun: Execute custom JavaScript code
• shuffle: Randomize data values within constraints
• And many more specialized transformation functions

User Functions

Custom functions that you create specifically for your project:

• Write JavaScript code to transform field values
• Test your functions with sample data before applying
• Reuse functions across different transformation rules
• Reference variables using the $(variable_name) syntax

Creating and Managing Functions

UI Overview

The Functions page presents a table view with the following columns:

Adding a New Function

1. Click the "Create" button in the top right corner
2. A right panel will open with a form containing:
   • Name: Text input for the function identifier (required)
   • Description: Text area for explaining the function's purpose (optional)
3. Fill in the required fields
4. Click "Save" to create the function and proceed to the code editor

Editing a Function

1. Click either:
   • The function name link to go directly to the code editor
   • The code icon in the actions column
   • The "Rename" option in the dropdown menu to modify metadata
2. In the code editor, you can:
   • Write JavaScript code transformations
   • Test your code with sample values in real-time
   • See execution performance metrics
   • Insert available internal functions from the sidebar

Deleting a Function

1. Click the action menu (three dots) next to any function
2. Select "Delete" from the dropdown
3. Confirm the deletion in the modal dialog

Warning: Be careful when deleting functions. If a function is being used in model rules, removing it will cause those transformations to fail and some sensitive data might remain visible.

Writing Function Code

Editor Interface

The code editor features:

• JavaScript syntax highlighting
• Auto-completion for available functions
• Real-time testing with input/output table
• Performance metrics showing execution time
• Field name configuration for context

Context Variables

In your function code, you have access to several context variables:

• $val: The original value of the field being transformed
• $rec or _: The entire record object (all fields)
• $old: The original record before any transformations
• $meta: Metadata about the current entity and field
• $vars: Project variables that can be referenced with $(variable_name)

Available Functions

The right sidebar in the code editor shows a list of available internal functions you can use:

• Faker functions: Generate realistic fake data (names, addresses, etc.)
• Encryption functions: Encrypt/decrypt values
• Utility functions: Various helper functions for data manipulation
• Hash functions: Generate hashed values (SHA, MD5, etc.)

When you click on a function in this list, its signature will be inserted into your code at the current cursor position.

Testing Your Code

The editor includes a built-in testing environment:

1. Enter sample input values in the "Old Value" fields
2. Click "Run" or press Ctrl+Enter/Cmd+Enter to execute your code
3. See the transformed output values in the "New Value" column
4. Monitor performance metrics to ensure efficient execution

Using Functions in Transformations

In Model Rules

Functions are used in model transformation rules by specifying the "code" action and referencing your function:

return $val + 10;

Or using other available functions:

return faker.internet.email();

Referencing Variables

You can reference project variables in your function code using the syntax:

return $(api_key);  // References a variable named "api_key"

This is useful for accessing configuration values or sensitive data without hardcoding them.

Best Practices

1. Descriptive names: Use clear, descriptive names for your functions to make their purpose evident
2. Documentation: Add descriptions to explain what each function does
3. Testing: Always test your functions with various input values before applying them
4. Performance: Monitor execution time and optimize complex functions
5. Reusability: Design functions to be reusable across different fields and entities
6. Security: When using variables, ensure sensitive data is stored as "Secret" variables
7. Error handling: Consider edge cases and handle potential errors in your code

Example Use Cases

• Custom email formatting based on name fields
• Generating composite keys from multiple field values
• Implementing complex business rules for data transformation
• Creating specialized anonymization functions for your industry
• Formatting phone numbers or other structured data
• Generating sequential or pattern-based identifiers

Functions provide the flexibility to implement virtually any data transformation logic required for your specific use case.