Building on Salesforce: Lessons from Our First Year

When we started building Parsium, we made a deliberate choice: build natively on the Salesforce platform rather than as an external service that connects via API. That decision shaped everything from our architecture to our security model to how we think about user experience. A year in, here's what we've learned.

Why Native Matters

External integrations create friction. Data leaves the org, gets processed somewhere else, and comes back. That round trip introduces latency, security considerations, and failure points. For document processing specifically, it means customer data (potentially sensitive documents) travels through multiple systems.

Building natively on Salesforce means the user never leaves their environment. The Parsium interface lives inside Salesforce. Document processing happens through secure API callouts using Named Credentials, which Salesforce manages and encrypts. Extracted data saves directly to records without intermediate storage. The security model inherits Salesforce's own infrastructure.

From a user adoption perspective, this matters more than most technical decisions. When a tool feels like part of Salesforce rather than a separate app, the adoption curve flattens. Users don't need to learn a new interface, manage separate credentials, or context-switch between systems.

Named Credentials: The Right Way to Handle API Keys

One of the earliest architecture decisions was how to manage the OpenRouter API key that Parsium uses for AI model access. We could have stored it in a custom setting, a custom metadata type, or even (shudder) a hardcoded string. Instead, we built the entire integration around Named Credentials.

Named Credentials are Salesforce's built-in mechanism for securely storing and managing external service authentication. The API key is encrypted at rest, managed through Salesforce's security framework, and never exposed in code or logs. When Parsium makes a callout to OpenRouter, Salesforce injects the authentication header automatically.

This approach has several practical benefits. Admins can rotate the API key without modifying code. The credential is protected by Salesforce's permission model. And during security reviews, we can point to Named Credentials as a platform-standard pattern rather than defending a custom implementation.

Permission Sets: Granular Access Without Profiles

Salesforce profiles are a blunt instrument. Permission sets let you layer specific access on top of existing profiles without modifying them. For Parsium, we built two permission sets: one for users (access to the UI and basic extraction features) and one for admins (field mapping configuration, model selection, and usage monitoring).

This keeps the installation lightweight. No custom profiles to create, no existing profiles to modify. Admins assign the appropriate permission set and users immediately have the right level of access. It also simplifies troubleshooting: if a user can't access Parsium, check the permission set assignment first.

What We'd Do Differently

Not everything went smoothly. Our initial UI used heavy custom CSS that clashed with Salesforce's Lightning Design System in certain contexts. We spent weeks refactoring to use SLDS tokens and design patterns, which we should have done from the start. If you're building on Salesforce, start with SLDS. Don't bolt it on later.

We also underestimated the importance of error messages. When an API callout fails, users don't care about HTTP status codes. They need actionable guidance: 'Your OpenRouter API key may have expired. Contact your Salesforce admin to update the Named Credential.' Every error state in Parsium now includes a plain-language explanation and a next step.

Finally, testing on different Salesforce editions and org configurations took longer than anticipated. A feature that works perfectly in a developer org can behave differently in an Enterprise Edition org with complex sharing rules, record types, and validation rules. We built a suite of integration tests that run against multiple org configurations before every release.

Looking Ahead

Building on Salesforce isn't easy, but it's the right choice for tools that live in the CRM workflow. Users shouldn't have to leave Salesforce to process documents. Admins shouldn't have to manage another external system. And security teams shouldn't have to evaluate another third-party data pipeline.

Our roadmap continues to lean into Salesforce-native capabilities: Flow integration for automated document processing triggers, support for additional standard and custom objects, and deeper alignment with Salesforce's evolving AI strategy. The platform keeps getting better, and so does what we can build on top of it.