User Sync Utility Apps are specialized workflow applications designed to synchronize employee data between an external HRIS (Human Resource Information System) and Leena AI's employee directory. They operate as webhook-triggered, autonomous workflows — structurally similar to Dynamic Dropdown Utility Apps — but purpose-built for pulling, transforming, and loading employee records in a paginated, repeatable manner.

When created, the system auto-provisions a three-node workflow (Trigger → Mapper → End), a pagination form tailored to the chosen pagination strategy, and a response template for returning structured employee data. The workflow executes synchronously as a single unit and runs under a dedicated system identity ([email protected]), meaning it does not require a human initiator.

---

When to Use a User Sync Utility App

User Sync Utility Apps are the right choice when you need to:

• Pull employee data from an external HRIS (such as Workday, UKG Pro, SAP SuccessFactors, or a custom SFTP source) into Leena AI's employee directory.
• Transform and map raw HRIS data into the standardized employee schema before loading it into the platform.
• Support paginated data retrieval — whether the source system uses page-number-based or skip-token-based pagination.
• Automate recurring syncs using a cron pattern, so the employee directory stays current without manual intervention.
• Add custom business logic between data retrieval and loading — for example, filtering out terminated employees, enriching records from a secondary source, or running validation checks.

Example: An enterprise customer integrates Workday with Leena AI. A User Sync Utility App is configured to call the Workday employee listing API with page-based pagination. The Mapper node transforms the Workday response fields (e.g., Worker_ID, Legal_Name) into Leena AI's internal schema (e.g., employeeId, displayName). The sync runs on a nightly cron schedule, and the response template feeds data back into the platform's employee directory service.

---

How It Works

Overview of the Execution Flow

1. Trigger — An external system (typically the HRIS sync scheduler or the platform's cron job) sends a webhook request to the User Sync Utility App, passing pagination parameters (page/pageSize or skipToken/pageSize) and optionally any filter data.
2. Autonomous Execution — The ExecuteEmployeeSyncService validates the application, confirms it is an active, published Employee Sync Utility, and initiates the workflow under the [email protected] system identity.
3. Workflow Processing — The AutonomousSyncExecutionHelperService traverses the workflow graph synchronously from the Trigger node through all intermediate nodes to the End node. This is a single-pass, blocking execution — the caller receives the response only after the entire workflow completes.
4. Response Building — The Trigger node's response template assembles the final output, pulling transformed data from the Mapper node and pagination metadata (page, pageSize, hasNext, total, skipToken) from the configured fields.
5. Status Update — The workflow item and session are marked as COMPLETED (or FAILED if execution encountered an error). On failure, the session status is set to FAILED and an empty response is returned gracefully.

Workflow Structure

The User Sync Utility App is provisioned from the Employee Sync Utility Template (employee-sync-utility.template.ts). The generated workflow has a fixed three-node structure:

Edges:

• Trigger → Mapper
• Mapper → End (includes a Purge menu option on the edge, which allows clearing intermediate data)

Pagination Modes

A key design decision at creation time is the pagination type. This determines which fields appear on the auto-generated "Pagination & Search" form and which response template fields are visible in the builder.

Page-Number Pagination (page)

When you choose page-number pagination, the system provisions form fields for pageSize and page, and the response template exposes pageSize and page fields (hiding hasNext and skipToken).

This mode is appropriate when the HRIS API supports traditional offset/page-based pagination (e.g., "give me page 3 of 50 records each").

Skip-Token Pagination (skipToken)

When you choose skip-token pagination, the system provisions form fields for skipToken and pageSize, and the response template exposes hasNext and skipToken fields (hiding page, pageSize, and total).

This mode is appropriate for APIs that return an opaque continuation token with each response (e.g., Microsoft Graph API, some SAP OData endpoints).

No Pagination

If pagination is not enabled on the application (employeeSync.pagination = false), all pagination-related response template fields are hidden, and no pagination form fields are generated. The workflow simply processes a single batch of data.

---

Creating a User Sync Utility App

Step 1: Create a New Application

Navigate to Workflows Studio > App Listing and click Create App. In the creation dialog:

• Set the Utility Type to EMPLOYEE_SYNC_UTILITY.
• Provide a descriptive Name (e.g., "Workday Employee Sync").
• Configure the Employee Sync settings:
  • pagination: Set to true if the HRIS API requires paginated calls.
  • paginationType: Choose either page (page-number) or skipToken (continuation-token).

The system automatically sets the trigger type to WEBHOOK and provisions the workflow, form, and response template.

Step 2: Review the Pagination & Search Form

The template auto-generates a single form titled "Pagination & Search" with fields determined by the pagination type:

For page-number pagination:

For skip-token pagination:

The form builder for this utility is partially locked — you cannot add new forms, and the pre-configured pagination fields are not visible as form components (their structure is managed by the template). However, you can add additional fields to the form using a controlled set of allowed components: Text, Dropdown, Master Select, Async Select, and Select.

Step 3: Configure the Mapper Node

The Mapper node is where you define how incoming HRIS data maps to the output schema. Open the Mapper node and configure the field mappings to transform source fields (from the Action node output) into the target employee data structure.

The Mapper node in a User Sync utility has the EMPLOYEE_SYNC_UTILITY variant set in its metadata, which tells the platform to apply sync-specific behavior during execution.

Step 4: Configure the Response Template

Open the Trigger node and configure the Response Template fields:

The visibility of these fields is automatically managed based on the pagination mode chosen during app creation.

Step 5: Add Business Logic (Optional)

Between the Trigger and Mapper nodes (or between Mapper and End), you can insert additional nodes to implement custom business logic. The following node types are allowed in a User Sync Utility App:

• Decision — Conditional branching based on data values.
• Merge — Combine data from parallel branches.
• Branch — Split execution into parallel paths.
• Action — Call external APIs or Synapse connectors (typically the HRIS API call).
• Function — Execute custom JavaScript logic for data transformation or validation.
• Mapper — Additional data mapping stages.
• Sticky Note — Documentation annotations (non-executing).

Step 6: Publish

Review the workflow and form configuration. When ready, Publish the app to activate it. The app will be available for webhook invocation.

---

Execution Identity

Unlike standard workflow applications where a real user initiates the workflow, User Sync Utility Apps run under a system identity:

• Name: Employee Sync
• Email: [email protected]
• Employee ID: [email protected]
• User ID: [email protected]

This means all workflow items, sessions, and audit trails created during a sync execution are attributed to this system user, not to a human operator. This is important for reporting — you can filter sync sessions by this initiator to isolate automated sync runs from manual workflow executions.

---

API Endpoints

The User Sync Utility App exposes two REST endpoints:

1. Get App Details

GET /employee-sync-utility/app-details?botId={botId}&appId={appId}

Returns the application details and a fresh sessionQueryToken. The caller should use this token when calling the execute endpoint to link the execution to a session.

2. Execute Sync

POST /employee-sync-utility/execute?botId={botId}&appId={appId}&sessionQueryToken={token}

Body: JSON object containing the form data (pagination parameters and any custom fields).

Returns the structured response as defined by the Trigger node's response template, including the data array and pagination metadata.

Both endpoints require workflowsV2 resource permission via ACL middleware.

---

Reporting

User Sync Utility Apps have dedicated reporting support through specialized report services:

• Employee Sync Reports (EmployeeSyncReports) — Aggregated session-level metrics filtered by the EMPLOYEE_SYNC_UTILITY utility type. Includes status count cards, percentage change calculations, and tabular session summaries.
• Employee Sync Detail Reports (EmployeeSyncDetailReports) — Granular item-level reporting for individual sync executions within a selected date range.

These reports are accessible through the platform's reporting dashboard and can be filtered by application, date range, and initiator. Scheduled reports are not available for User Sync Utility Apps (the configuration hides the scheduled reports setting).

---

Curated Builder Experience

The User Sync Utility App provides a curated builder interface that balances flexibility with template integrity:

---

Integration with Sync Settings

The User Sync Utility App works in conjunction with the platform's Sync Settings (SyncSettingsModel), which governs the broader employee synchronization lifecycle:

• Sync Tags — The sync settings define which workflow tags to execute during a sync cycle. The User Sync Utility App is identified by its tag and invoked accordingly.
• Cron Pattern — Defines the recurring schedule for automatic sync execution.
• SFTP Settings — If the HRIS data source is an SFTP server rather than an API, the sync settings hold the connection parameters (host, port, username, password with encryption support).
• Alerts — Configurable email alerts for sync failures or anomalies, including company branding and check definitions.
• Terminate Other — A flag that, when enabled, terminates employees in the directory who are not present in the latest sync data.
• Pause — The sync can be paused without deleting the configuration.

The User Sync Utility App handles the data retrieval and transformation portion of this lifecycle; the broader sync orchestration (scheduling, alerting, termination logic) is managed by the platform's integration layer.

---

Key Considerations

• Webhook-Only Trigger: User Sync Utility Apps always use a WEBHOOK trigger type, enforced at creation time. They cannot be switched to manual trigger.
• System Identity: All executions run under [email protected]. There is no human initiator, so features like "initiated by" filtering in general reports exclude sync utility sessions.
• Not Publishable as Template: User Sync Utility Apps cannot be published as global templates. They are designed to be created fresh from the utility template for each integration.
• Visibility: Like other utility apps, they are excluded from the end-user application catalog and can be filtered in the App Listing dashboard using the utility app filter.
• Pagination Choice is Structural: The pagination type (page vs skipToken) determines the form structure and response template visibility at creation time. To change pagination strategy, create a new User Sync Utility App with the desired type.
• Synchronous Execution: The entire workflow runs synchronously — the webhook caller blocks until the workflow completes and receives the full response. Long-running sync logic should be designed with this in mind.
• Session Tracking: Each execution creates a workflow session tagged with EMPLOYEE_SYNC_UTILITY, enabling dedicated reporting and filtering separate from standard workflow sessions.
• Auto-Documentation: The platform supports AI-assisted documentation generation for User Sync Utility Apps, labeled as "Employee Sync Utility" in the documentation system.
• Versioning: Standard versioning applies — changes are made on a draft version and published as immutable snapshots, with full version history and restore capability.