For AI agents: an index of this documentation is at https://developer.rippling.com/llms.txt. Public pages have a Markdown version at the same URL with .md added.

Skip to main content
Article

Custom solution best practices

Use Rippling's best practices when building custom solutions.

Use with AI:Rippling AI ChatGPT Claude Cursor

Data ingestion & modeling​

How data is structured and moved prior to building a custom solution prevents major bugs and rework later. Follow these core principles before building:

  • Define a single sources of truth per field - Before writing code, decide which system owns each piece of data so two systems never overwrite the same field. If two systems must update the same field, build rules to handle conflicts before launch.
  • Map out permissions before finalizing the data model - Decide who can view, create, edit, or delete each type of record. Access requirements directly shape how custom objects are structured.
  • Keep incoming data separate from working data - Store imported data in a "raw" custom object that matches the external system's exact format. Then, clean and map that data into a separate "working" object that automations and rules actually run on. If the external tool changes its format later, only update the import mapping.
  • Use a staging step before updating live systems - Group and hold calculated records in a staging object so they can be reviewed and approved before hitting Payroll or an external tool. This gives a clear audit trail and a safety net. Only bypass staging for low-risk or read-only actions.
  • Use permanent IDs for lookups and bulk updates - Always search and match records using stable, indexed fields like id or external_id rather than values that might change. When running bulk updates, match on external_id so re-running an automation updates existing records instead of creating duplicates.

Processing & reliability​

Design functions and automations to handle retries, partial failures, and sensitive math without creating duplicate records or broken payouts.

  • Prevent duplicate actions on re-runs - Build functions and automations so running them twice with the same input won't duplicate records or double-post data. Use automation run IDs, API idempotency keys, or predictable external IDs to safely skip work that has already succeeded.
  • Give admins a manual override - Every automated flow should have a manual trigger so admins can step in and run it on demand if a scheduled job fails or runs late.
  • Handle temporary glitches differently from data errors - Automatically retry temporary issues (e.g., network timeouts or API rate limits) with increasing delays between attempts. For data or logic errors, such as missing configuration or invalid records, stop retrying and route the record to a manual-review state with a clear error message.
  • Verify incoming data before processing - Add a pre-run check before critical jobs (such as payroll runs) to confirm that all expected records have landed in Rippling.
  • Track processing status on every record - Store the lifecycle state directly on the records driving external updates. Include fields for current status, timestamps, retry counts, last attempt time, and error reasons so you can easily troubleshoot failures.
  • Calculate money in whole cents - Avoid floating-point rounding errors by converting dollar amounts to whole cents for all math, and round to the final currency format only at the very end.
  • Keep 4 decimal places for hours - Preserve hours to 4 decimal places during earnings calculations so your math aligns with Rippling Time & Attendance, which tracks time down to the second.

Latency & performance​

Build your schedules and functions with timing buffers and shared platform limits in mind so your automations don't miss critical deadlines or get throttled.

  • Add buffer time to your schedules - Pipelines, transformations, and automations don't always finish on the exact minute; a job scheduled every 60 minutes may take closer to 75 minutes to complete. Measure how long your automations actually take and build in extra buffer before committing to strict deadlines (like payroll cutoffs).
  • Use scheduled triggers for fixed deadlines - When an automation needs to run at a predictable time, use a time-based schedule rather than an event-based trigger. Event-based automations can slow down when platform traffic is high.
  • Don't rely on formula fields for real-time logic - Formula fields can take up to 24 hours to recalculate. If an automation or function needs strict values, calculate them directly in your logic instead of reading from a formula field.
  • Batch your work to stay within execution limits - Function execution limits are shared across your entire company, including all automations, pipelines, and CLI calls. Instead of triggering a separate function run for each employee, group records together and process them in batches.

Simplicity & maintainability​

Keep your solution easy to update and scale without rewriting core logic every time business rules change or headcount grows.

  • Build only what you need - Use the fewest custom objects, automations, functions, and pipelines required to solve the problem. Fewer moving parts make your app easier to debug, maintain, and hand off to others.
  • Keep business rules out of your code - Store configurable values (e.g., rates, thresholds, or eligibility rules) in settings, custom objects, or lookup tables instead of hardcoding them into if/else statements. That way, admins can update rules without editing or redeploying code.
  • Always paginate queries and plan for scale - Never assume a query will return all records in a single page. Always loop through paginated results until no records remain, and design your logic with batching and rate limits in mind.
  • Run functions asynchronously by default - Use asynchronous functions for background processing so automations don't stall or time out. Save synchronous functions strictly for real-time user actions where someone is actively waiting on an immediate response.

Customer experience & operations​

Make your solution intuitive for admins to run, easy to monitor day-to-day, and safe from accidental changes or silent failures.

  • Show record statuses directly in the app UI - Display clear status badges, such as Pending, Processing, Pushed, Failed, Skipped, or Manual Review, inside your app interface so admins can track progress and spot issues without digging into raw custom objects.
  • Give users a dedicated interface instead of backend tools - Build clean custom app pages or guided automations for everyday tasks rather than asking admins to work directly inside the Catalog.
  • Prevent invalid clicks and confirm every action - Disable buttons that don't apply to a record's current status (for example, hiding or graying out "Approve" once a record is already pushed). Return clear messages from backend functions, and automatically refresh the screen or show a banner alert so users know their action worked.
  • Require admin sign-off before high-risk updates - Pause automations and require explicit human review and approval before writing sensitive data to Payroll or external systems.
  • Set up automated health checks - Run scheduled checks to verify that API tokens are still valid, external connections are active, and incoming data isn't stale. Route alerts directly to your team's existing monitoring channels (like Slack or email) so you catch silent breakages before users do.

See also​