Overview

Custom API Actions now support flexible, expression-based query parameter formatting. This unlocks compatibility with enterprise APIs that require advanced query syntax, including Oracle HCM and similar platforms that retrieve user-specific data via encoded expressions.

Who this is for: Admins, App Managers, and Integration Managers configuring external API actions in Simpplr.

What’s new

• Support for raw query expressions in query parameters (for example, q=personNumber=1471230).

• Dynamic variable substitution in expressions (for example, q=personNumber={{employeeNumber}}).

• Accurate runtime resolution: variables resolve to the signed-in user or action context values at execution.

• Optional control to bypass automatic URL encoding for supported parameters, so expression structures aren’t altered.

• Improved validation with clear, actionable error messages for malformed expressions or missing variables.

Why it matters

• Enterprise HRIS and ERP systems frequently use expression-based filters in a single parameter (for example, q, where, search).

• Previously, strict key/value parsing or forced encoding could break these expressions. The new behavior preserves intent and structure.

• Enables powerful, user-aware actions like “Fetch my PTO balance,” “Get my pay period,” or “Show my assigned learning,” without custom middleware.

Examples

Oracle HCM: filter absences by personNumber

Configured input:

• Key: q

• Value: personNumber={{employeeNumber}}

Resolved request at runtime:

/hcmRestApi/resources/latest/absences?q=personNumber=1471230

Expression with multiple conditions

Configured input:

• Key: q

• Value: personNumber={{employeeNumber}};status=APPROVED

Resolved request:

/hcmRestApi/resources/latest/absences?q=personNumber=1471230;status=APPROVED

Using profile-driven variables

Configured input:

• Key: q

• Value: workEmail={{user.email}}

Resolved request:

/hcmRestApi/resources/latest/workers?q=workEmail=jane.doe@company.com

How to configure

1. Go to Manage, then Integrations, then Custom API Actions, and create or edit an API action.

2. In Query Parameters, click Add parameter.

3. Enter the parameter key used by your target API (for example, q, search, or where).

4. Enter the full expression in Value using variables as needed (for example, personNumber={{employeeNumber}}).

5. (Optional) Disable automatic encoding for this parameter if your API expects raw expressions.

6. Save and use Test action to verify the resolved request and response.

Dynamic variables

Use double-curly syntax to reference runtime values:

• {{employeeNumber}} , the user’s employee number (if mapped in your directory or user profile).

• {{user.email}} , the authenticated user’s email.

• {{user.id}}, {{user.firstName}}, {{user.lastName}} , common profile fields.

• {{context.*}} , values passed from the invoking surface (where supported).

Behavior and validation

• Preserves expression structure: The platform does not split or reformat expressions inside a single parameter.

• Encoding control: When “Disable automatic encoding” is selected, supported parameters are forwarded as-is.

• Pre-execution checks: The system validates required variables and basic expression shape. If a required variable is empty or the expression is malformed, a clear error is shown before the outbound call.

• Backward compatibility: Existing Custom API Actions continue to work unchanged.

Best practices

• Confirm the exact parameter key and syntax required by the source API (for example, Oracle HCM often uses q with semicolon-delimited conditions).

• Use the Test action tool with representative users to ensure variables resolve as expected.

• Prefer precise identifiers (for example, personNumber over names) to avoid ambiguity.

• Only disable encoding for parameters the source API expects in raw form. Keep encoding on for all others.

• Start simple (single condition), validate, then add additional conditions.

Troubleshooting

Identify your issue below, understand what happened, and take the right action.

Your variable isn’t resolving at runtime

• What happened: The variable you referenced (for example, {{employeeNumber}}) isn’t present in the user’s profile mapping, or your identity sync or field mappings aren’t populating it.

• What to do: Ensure the referenced variable is present in the user’s profile mapping. Check your identity sync or field mappings, and re-test with a user who has a populated value.

The target API rejects the request or returns an unexpected response

• What happened: The expression format or delimiter you used doesn’t match what the target API expects, or automatic URL encoding is altering the expression structure.

• What to do: Verify the target API’s expected expression format and delimiters. Some endpoints require semicolons (;) or specific field names. Try disabling automatic encoding for the parameter if the API expects raw expressions.

Your expression is being altered or encoded when sent

• What happened: Automatic URL encoding is on for the parameter, so special characters in your expression are being encoded before the request goes out.

• What to do: Edit the query parameter and select “Disable automatic encoding” for that parameter, then re-test.

The API returns the wrong user’s data

• What happened: The expression may not be using a user-specific field, or the runtime variable you referenced doesn’t map to the user you intended.

• What to do: Confirm you used a user-specific field (for example, personNumber or workEmail), and that the runtime variable is correct (for example, {{employeeNumber}} versus {{user.id}}). Validate with the Test action as the intended user.

FAQs

Q: Will my existing Custom API Actions still work after this change?

Ans: Yes. Existing Custom API Actions continue to work unchanged. The new behavior is additive and doesn’t affect prior configurations.

Q: When should I disable automatic encoding for a parameter?

Ans: Only disable encoding for parameters the source API expects in raw form, such as expression-based filters where encoding would alter the structure. Keep encoding on for all other parameters.

Q: Which fields can I reference as dynamic variables?

Ans: You can use {{employeeNumber}} (if mapped in your directory or user profile), {{user.email}}, {{user.id}}, {{user.firstName}}, {{user.lastName}}, and {{context.*}} values passed from the invoking surface where supported.

Q: What happens if a required variable is missing or empty at runtime?

Ans: The system runs pre-execution checks and shows a clear error before the outbound call is made, so a request with a missing variable won’t be sent to the target API.

Q: Does this change affect headers, request body, or write operations?

Ans: No. Only query parameters are affected. Headers and body content behavior is unchanged, and the enhancement is designed for read operations that require expression filters. Behavior for write operations is unchanged.

Security and compatibility notes

• Only query parameters are affected; headers and body content behavior is unchanged.

• This enhancement is designed for read operations that require expression filters; behavior for write operations is unchanged.

• Masks are enforced on sensitive fields throughout configuration (see “Masked Credential Fields for Integrations and App Tile Configurations”).