Macros

    Macros are placeholders used to automatically fetch real-time data, such as user attributes or system values, and insert them into webhooks, templates, and scripts.

    They help avoid manual data entry and enable dynamic, automated processes.

    How macros work

    Macros act as dynamic placeholders that are resolved during execution. Each macro follows a defined syntax, where a prefix identifies the data source (such as Active Directory, Microsoft 365, or environment settings) and the macro name specifies the value to be retrieved.

    The supported syntax formats are:

    • %<prefix>.<macroname>%
    • %<prefix>.<macroname>(Arg1, Arg2, ...)%
    • %<prefix>.<macroname>(#%<prefix>.<macroname>%#, Arg2, ...)%

    When a macro is used in a webhook, template, or script, the product processes it at runtime by identifying the macro, retrieving the corresponding value from the specified source, and replacing it with the actual value. This enables configurations to dynamically adapt based on real-time data and ensures that accurate information is passed to the target system during execution.

    How can you use macros?

    Click the macro selector icon-percentage icon in the modules listed below that support macros, and configure them as needed.

    Note
    • Macros are case-sensitive, and incorrect casing may prevent proper resolution.
    • If a macro is invalid or undefined, it will return an empty value during execution.
    • Incorrect macro syntax will result in the macro not being processed.
    • Nested macros must be enclosed using # to function correctly.
    • The availability of certain attributes depends on the Active Directory or Microsoft 365 configuration.

    Different types of macros

    Type of macro Prefix Available macros
    Action details act
    Environment variable env
    Custom functions fx
    Utility -
    AD attributes ad
    Microsoft 365 attributes m365

    Nested macros

    Nested macros allows for a macro to be embedded or called inside another macro. You can use nested macros by enclosing the inner macro with #. The Environment Variable, Find and Replace Macros, Encode and Decode URI Component Macros are examples of nested macros.

    Syntax

    %<prefix>.<macroname>(#%<prefix>.<macroname>%#, Arg2, ...)%

    Example

    %fx.findAndReplace(input:#%ad.OU_DN_NAME%#,find:test.com,replace:test123.com)%

    Input value Output value
    If a user OU's, DistinguishedName = "OU=IAM users,DC=test,DC=com". "OU=IAM users,DC=test123,DC=com"

    Active Directory macros

    Active Directory macros are used to retrieve user and object attributes directly from AD. Custom attributes can be configured under Admin > LDAP Attributes. While adding custom attributes, make sure they are associated with the relevant report category.

    Supported Active Directory macros

    • isDeleted
    • givenName
    • sn
    • initials
    • distinguishedName
    • OU_DN_NAME
    • userPrincipalName
    • sAMAccountName
    • description
    • cn
    • displayName
    • name
    • OUName
    • memberOf
    • memberOf_dn
    • profilePath
    • mail
    • homeDirectory
    • scriptPath
    • password
    • streetAddress
    • postOfficeBox
    • l
    • co
    • telephoneNumber
    • homePhone
    • pager
    • mobile
    • facsimileTelephoneNumber
    • ipPhone
    • title
    • department
    • company
    • physicalDeliveryOfficeName
    • manager
    • manager_dn
    • info
    • c
    • homeMDB
    • mailNickname
    • objectSID
    • objectGUID
    • employeeID
    • employeeNumber
    • homeDrive
    • domainName
    Note All added custom attributes are dynamically available as macros.

    Microsoft 365 macros

    These macros retrieve user and resource attributes from Microsoft 365. By default, 18 Microsoft 365 attributes are available as macros in the product.

    Supported Microsoft 365 macros

    • City
    • Country
    • DecodedImmutableId
    • Department
    • DisplayName
    • Fax
    • FirstName
    • Office
    • PhoneNumber
    • PostalCode
    • State
    • StreetAddress
    • Title
    • UsageLocation
    • UserPrincipalName
    • EmailAddresses
    • MobilePhone
    • O365UserPrincipalName

    Action Details

    Timestamp

    Timestamp macros are placeholders or variables used to represent specific date and time values dynamically. To use this macro, select the Timestamp macro under Action Details and specify the date and time format for the values to be updated in real time whenever the macro is used.

    For example

    When automating user onboarding tasks, you can set the start date for user account creation to be two days after the automation configuration by using the timestamp macro as shown below.

    Syntax

    %act.timestamp_<dateformat>_<timeinterval type>_<timeinterval value>%

    Example

    %act.timestamp_dd-MM-yyyy_afterNDays_2%

    Input value Output value
    If the current date during macro parsing is: 01-01-2025 03-01-2025

    Environment variable

    An environment variable is a name or value pair that can be used as macros for values that rarely change, like Authtoken, IDs, etc. They can be used in the place of URL, Header, Parameter, and Message Body while creating a new webhook template.

    Syntax

    %env.<Variable name>%

    Example

    %env.securedToken%

    Input value Output value
    %env.securedToken% sd#123#78sd

    Custom functions

    Create custom functions whose value is retrieved from a script. The resulting value from the script execution while the variable macro is parsed will be used as the value of the custom function.

    Note You can also store the sensitive information in the script output's arguments and add that as a nested macro in the environment variable.

    Syntax

    %fx.<Variable name>_<Argument 1>_...<Argument n>%

    Example

    %fx.generateSecuredToken_#%act.timestamp_dd-MM-yyyy_current time%#_admin%

    Input value Output value
    %fx.generateSecuredToken_#%act.timestamp_dd-MM-yyyy_current time%#_admin% The generateSecuredToken script path will be added here.

    The execution time will follow the dd-MM-yyyy format (e.g., 01-01-2024) as the first argument, with admin as the second argument.

    Both values will be parsed in the script, and the script's output will become the macro's value.

    Find and replace

    Find and replace macro helps you search and find a specific part of the source string and replace it with another string. In the product, you can find and replace source strings and macros. To use this, in the Select Macros pop-up window, go to Functions > Find and Replace.

    Syntax

    %fx.findAndReplace(input:<inputValue>,find:<findValue>,replace:<replaceValue>)%

    Example

    %fx.findAndReplace(input:#%ad.OU_DN_NAME%#,find:test.com,replace:test123.com)%

    Input value Output value
    If a user OU's, DistinguishedName = "OU=IAM users,DC=test,DC=com". "OU=IAM users,DC=test123,DC=com"

    Encode URI

    The Encode URI macro works similar to the actual Javascript encodeURI component. By default, the API URL and parameters of webhook templates will be encoded before execution. Apart from these, if you want to encode any other values, use this option.

    Syntax

    %fx.encodeURIComponent("<value>")%

    Example

    %fx.encodeURIComponent("L*urO@82#")%

    Input value Output value
    L*urO@82# L*urO%4082#%0A
    Note You can also store the sensitive information in an environment variable and add that as a nested macro in the Encode URI macro.

    Decode URI

    The Decode URI macro works similar to the actual Javascript decodeURI component. If you want to decode the encoded attribute values fetched from the integrated application, then enter the value in the Decode URI Component field.

    Syntax

    %fx.decodeURIComponent("<value>")%

    Example

    %fx.decodeURIComponent("Ad%20secure%20pwd")%

    Input value Output value
    Ad%20secure%20pwd Ad secure pwd

    Retrieve Regex Matches

    This macro in the inbound webhook enables you to search and locate the desired pattern values from the configured endpoint's attribute columns. In the Retrieve Regex Match field (Select Macros > Functions), provide the column name and the pattern to search and match. Once done, click Add.

    This way, when data is fetched from the endpoint, it will include only the string pattern required for API processing and discard the rest in the attribute value.

    Note The Retrieve Regex Matches macro can only be used in naming formats.

    Utility

    Append

    If you want to use two macros consecutively, use the :APPEND: string in between them while fetching the data from the endpoints.

    Syntax

    %<prefix>.<macroname>%:APPEND:%<prefix>.<macroname>%

    Example

    %ad.givenName%:APPEND:%ad.department%

    Input value Output value
    If the user's given name is test and the department name is account. testaccount

    Tips

    Best practices

    • Always use the correct macro prefix (such as ad, m365, or env) to ensure values are retrieved from the intended source.
    • Verify the macro syntax carefully before saving configurations to avoid execution errors.

    Related references