Installation & Configuration

initial setup complete these steps in order the whole process typically takes 30–60 minutes, plus background time for the bulk match to finish choose your install audience 🔴 critical before you click install, decide how you want to control user access to the altrata app salesforce will ask you to pick one of three install options, and your choice has long term consequences if you want to choose roll altrata out to everyone in salesforce immediately, with no per user gating install for all users control which users get access to which altrata features (admin vs match manager vs end user) using altrata's built in permission sets install for admins only limit access to specific salesforce profiles (e g , only the "sales" or "development" profile) install for specific profiles 🛑 permission sets in salesforce are additive only once you grant a user access through a permission set, you cannot use permission sets to take it away — you can only stop assigning new ones this means the decision you make at install time is hard to reverse if you install for all users and later decide you wanted granular control, you'll have a much harder cleanup job 🟢 recommended if you're not 100% sure which path you need, choose install for admins only you can always grant access to more users later by assigning permission sets — but going the other direction (revoking access after a broad install) is much harder if you chose all users , you can skip ahead to step 1, then jump straight to step 2 (authenticate) permission set planning doesn't apply to you if you chose admins only or specific profiles , complete step 1 (install) and then proceed to step 1a — configure permission sets before continuing step 1 — install the package 🟡 required click the installation link production https //login salesforce com/packaging/installpackage apexp?p0=04tuc0000016sclia2 https //login salesforce com/packaging/installpackage apexp?p0=04tuc0000016sclia2 sandbox https //login salesforce com/packaging/installpackage apexp?p0=04tuc0000015sdviaq https //test salesforce com/packaging/installpackage apexp?p0=04tuc0000016sclia2 https //test salesforce com/packaging/installpackage apexp?p0=04tuc0000016sclia2 you'll be prompted to log in to salesforce confirm you're logging in to the correct environment (production vs sandbox) salesforce usernames are unique per environment, so double check before proceeding on the install page, select install for all users , then click install when prompted, approve third party access by checking yes, grant access to these third party web sites , then click continue wait for the install to complete it usually takes 5–10 minutes, but can take longer if you see this message, the install will continue in the background and the salesforce admin will receive an email when it's done about the "altrata" permission set you may notice that the altrata app ships with a single combined permission set called altrata permission set this is a convenience option that bundles all the access you'd normally get by assigning the five permission sets below you can use it if security isn't a primary concern for your rollout and you want a simpler, faster way to grant access you installed for all users and want a quick way to grant the same access to any new users you add later you should use the five individual permission sets (credential management, app configuration, background job execution, match management, standard capabilities) if you want fine grained control over who can do what, or if your organization requires least privilege access both approaches work the same way for end users pick whichever fits your security posture step 1a configure permission sets ℹ️ skip this section if you installed for all users salesforce automatically grants access to every user in that case, and no further permission configuration is needed if you chose install for admins only or install for specific profiles , you'll need to manually grant access to the users who should be able to use the app the altrata managed package ships with five permission sets — combine them to give each user exactly the access they need 🟢 recommended plan permissions on paper before assigning them in salesforce identify who will administer the app, who will manage matches, and who will simply use altrata data on records the altrata permission sets altrata credential management contains only the permissions required for the initial setup of the altrata api credentials on the altrata authentication tab scope api credential creation, update, and verification access area altrata authentication tab (credential entry and validation ui) excludes broad administrative rights, data controls, and end user features typical assignees integration administrator, platform admin 🟢 best practice assign temporarily to the integration owner to complete api credential creation or rotation, then remove once setup is verified altrata app configuration contains the permissions required to administer the application post installation limited to data controls and match settings tabs scope application level settings, data control settings, configuration on match settings tabs use cases tuning matching thresholds, enabling and disabling features, managing settings excludes api credential provisioning (covered by credential management) typical assignees product owner, salesforce admin, application administrator altrata background job execution contains only the permissions required to execute background tasks such as matching and enrichment scope start, monitor, and re run background jobs (match runs, batch updates) capabilities jobs access, job visibility, reschedule and abort typical assignees background service user, operations scheduler 🟢 best practice assign this set to a dedicated integration user (not a human user) this keeps scheduling stable, avoids tying jobs to an individual user's license or session, and produces a clean audit trail altrata match management contains only the permissions required to manage, accept, or reject possible match results scope review candidate matches, accept and reject possible matches capabilities access to match management ui, filtered record views excludes starting background jobs, changing global configuration typical assignees data stewardship team, crm data quality leads altrata standard capabilities contains all the permissions required to interact with the non administrative functions of the application scope everyday end user workflows and ui navigation capabilities manual matching, advanced search, pathfinder, profile viewing, and other day to day features excludes administrative configuration, credential handling, job orchestration typical assignees general users, analysts, relationship managers additional salesforce permissions most user roles also need standard salesforce permissions on the objects they'll work with customize application (system permission, for admins) read access to lead, contact, and account write access to lead, contact, and account create access to lead, contact, and account modify metadata through metadata api functions how to assign permission sets in salesforce, go to setup → users → permission sets find the relevant altrata permission set (e g , altrata credential management ) click manage assignments → add assignments select the users who should receive this permission set and click assign repeat for each permission set / user combination from the model you chose above best practices assign credential management sparingly this permission set lets a user enter or change altrata api credentials, which controls the integration's data access limit it to the smallest possible group — ideally one or two trusted admins don't give standard users admin permission sets end users only need standard capabilities plus salesforce object permissions bundling admin sets in for convenience creates audit and security risk document your choice record which model you chose and which users hold each permission set this makes future audits, role changes, and offboarding much easier troubleshooting access issues if a user reports they cannot do something they expect to be able to do, use the table below to identify which permission set is likely missing symptom likely fix cannot enter api credentials ensure the user has credential management and access to the altrata authentication tab cannot edit data controls confirm app configuration is assigned, and verify the user has visibility to the data controls and match settings tabs background job fails to start assign background job execution to the user (or to the dedicated service account) and try again cannot accept or reject possible matches verify match management is assigned, and confirm record level sharing grants the user visibility to the records in question missing day to day app features assign or reassign standard capabilities and confirm object and tab visibility through the user's profile ℹ️ profiles and permission sets work together profiles control baseline object access and tab visibility permission sets layer additional rights on top if access still fails after assigning the right permission set, validate the user's profile level object permissions and sharing rules permission sets faq can one user hold multiple permission sets? yes you can combine sets to match a user's responsibilities while keeping privileges narrowly scoped the models a, b, and c above are common combinations, but you can build your own as needed when should i remove credential management? immediately after api credential setup is completed and the connection has been validated credential management is meant to be temporary, not a permanent assignment do end users ever need app configuration? no app configuration is for administrators managing application settings end users only need standard capabilities for their day to day work step 2 — authenticate the integration 🟡 required you won't be able to view or sync altrata data until the package is authenticated with your altrata service credentials in salesforce, click the app launcher (the 9 dot icon in the top left) in the search box, type altrata setting and click the result if you cannot locate altrata settings within the app launcher, ensure the application has been installed correctly and that you have the permissions to access open the altrata authentication tab enter your service account username, password and api key the api key should be received via a separate email click verify if verification fails, double check that yo've entered each value exactly as provided if the error persists, contact your customer support representative step 3 — configure field mapping 🔴 critical match settings is where you tell the integration which salesforce fields to use for matching (field mapping) and which salesforce records are eligible for matching (data filters) getting both right before you run bulk matching is the difference between a smooth rollout and a frustrating cleanup project why this step is critical field mapping tells the matching algorithm which salesforce fields to read from when finding the best altrata profile for each record the richer your mapping, the better the match rate and match quality — map as many fields as possible matching requires at least one of these four methods to be fully configured first name + last name + organization name — all three mapped together first name + last name + zip code — all three mapped together first name + last name + any address field — all three mapped together email — at least one email field mapped linkedin url — linkedin profile url mapped foundation brand person/organization id — a profile id from another altrata brand (boardex, relsci, or wealth x) you can configure multiple methods simultaneously — and should, when possible records that satisfy more methods produce stronger, higher confidence matches 🔴 migrating from a foundation app (boardex, relsci, or wealth x)? read this carefully if your organization is migrating from a legacy altrata foundation app — boardex , relsci , or wealth x — it is strongly recommended to map your existing foundation brand person/org id to the corresponding altrata field on each object the mapping pairs are boardex individual id (salesforce) → boardex person id (altrata) boardex organization id (salesforce) → boardex organization id (altrata) relsci entity id (salesforce) → relsci person id (altrata) relsci entity id ( salesforce) → relsci organization id (altrata) wealth x dossier id (salesforce) → wealth x person id (altrata) why it matters every record already matched in your foundation app has a foundation brand person / org id stored in salesforce mapping that id into altrata tells the matching engine "this record is already known — preserve the existing match " without this mapping, the bulk match starts from scratch and you risk records re matching to a different altrata profile than they had in the foundation app duplicate matches across legacy and new data loss of identity continuity in reports, dashboards and downstream automations manual cleanup work to reconcile mismatches after the fact action — before running bulk matching open field mapping in the altrata app for each object you use (leads, contacts, accounts, person accounts), locate the foundation brand person id field on the altrata side map it to the salesforce field that currently stores your foundation brand ids save each object tab if you're not sure where your foundation brand person ids live in salesforce, check with the admin who managed your previous foundation app or contact support\@altrata com for help locating them how to configure field mapping from the altrata app, open match settings → field mapping by default, you'll see three object tabs leads , contacts and accounts if your instance has person accounts enabled, person accounts appears as a fourth tab (person accounts are not required ) for each object, review and map fields use the on screen guidance at the top of the page to confirm at least one of the four matching methods is fully configured map any foundation brand id fields (boardex, relsci, wealth x) if you're migrating from one of those apps — see the callout above where the altrata data model has multiple variants of a field (e g , separate personal and professional email fields), map each to the most appropriate salesforce field if your salesforce instance only stores one variant, map it to whichever altrata field best reflects your data save your changes on each tab 3b data filters 🟢 recommended data filters let you control which salesforce records are eligible for altrata matching on a per object basis without filters, every lead, contact, account, and person account in your instance is considered for matching — which can produce noise, unintended bulk matches, and wasted match capacity on records that don't need enrichment (e g , closed lost leads, internal test records, archived contacts) filters apply before the next bulk match begins and improve match quality by narrowing the eligible record pool to what's commercially relevant how to configure data filters from the altrata app, open match settings → data filters for each object — contact , lead , person account , account — enter a filter expression in the input field click save changes filters take effect on the next scheduled or manual bulk match — they do not retroactively unmatch records that have already been matched filter syntax data filters use a soql where clause expression (without the where keyword itself) reference any standard or custom field on the object, combine clauses with and / or, and use standard salesforce operators (=, !=, in, like, etc ) soql filter examples don't match household accounts recordtype developername != 'hh account' note t he developername is different for different org types npsp — hh account (label "household account") nonprofit cloud — household on account, or industrieshousehold depending on version fsc — industrieshousehold (older orgs household) match only active contacts with a corporate email domain isdeleted = false and email like '%@%' and email not like '%@gmail com' exclude closed lost or disqualified leads status not in ('closed not converted', 'disqualified', 'unqualified') limit person accounts to a specific region billingcountry in ('united states', 'canada') and ispersonaccount = true combine multiple criteria — high value, recently active contacts accountid != null and lastactivitydate >= last n days 90 and account annualrevenue > 5000000 ⚠️ validate filter expressions before saving invalid soql will be rejected when you click save test complex expressions in salesforce developer console or workbench first if you're unsure 🟢 best practice start with broad filters that just exclude obvious junk (deleted records, test data, closed lost), run a bulk match, and tighten from there based on what you see in match management over filtering on the first pass risks excluding records you actually wanted matched match settings checklist before moving to the next step, confirm at least one of the four matching methods is fully configured on every object (excluding the account object) you use if migrating from boardex, relsci, or wealth x the foundation brand ids are mapped on every relevant object if your records hold both personal and professional emails each is mapped to its corresponding altrata email field data filters have been reviewed for each object — even if you choose to leave them blank, that should be a deliberate decision you've clicked save on every field mapping object tab and on data filters step 4 configure page layouts 🟡 required by default, your salesforce pages will not include altrata components adding these components is critical to view altrata data on salesforce page layouts for the supported objects the following instructions assume you are leveraging salesforce lightning if you are leveraging salesforce classic please contact support\@altrata com mailto\ support\@altrata com configuring the altrata tab to include the altrata components on your lead , contact , and/or person account record pages, begin by navigating to the relevant record page this must be done for each page layout individually where altrata data will be displayed if you have multiple page layouts for a single record type, verify you are modifying the correct page layout once on the record page, click the gear icon in the top right corner click edit page as shown below, click on the whitespace next to your existing tabs this will open a prompt to create a new tab click on the add tab button on the right rail as show above by default, a new details tab will be created click the newly created details tab at the bottom of the list be careful not to edit your existing details tab! only edit the tab at the bottom of the tab list within the tab label dropdown, select custom at the top of the list we recommend naming this tab altrata click done you should now have a new tab named altrata at the bottom of the list save the page layout configuring page components now that the tab has been created to house altrata elements, those elements may be dropped on the relevant page layouts this must be done for each page layout individually, where altrata data will be displayed manual matching components to enable manual matching on a per record basis, the altrata link unlink must be placed on the page while this is optional, it is highly recommended that you include this element in your page layouts for ease of use in the left hand rail search bar under components , type altrata link unlink click and drag the component to your desired location on the page we recommend the right rail of your page layout if your layout supports it otherwise, we recommend at the top of your altrata tab altrata detail components the managed package offers two methods for displaying altrata data either as a single element or as customizable individual components in most cases, we recommend implementing the former , however, the latter can be leveraged when certain data points are not relevant or should not be displayed for any reason in the left hand rail search bar under components , type altrata person full detail for leads , contacts , and person accounts for accounts, type altrata account full detail ensure you are using the correct element for the object, otherwise, data will not display as expected click and drag the component to your desired location on the page we recommend within the altrata tab you created earlier in this guide click save in the left hand rail search bar under components , type altrata person for leads , contacts , and person accounts for accounts, type altrata account this will allow you to place the elements found in the full detail element individually based on your needs click and drag the component to your desired location on the page we recommend within the altrata tab you created earlier in this guide click save step 5 bulk matching 🟢 recommended while records can be matched manually, it is highly recommended that the automated bulk matching be initiated for the best experience bulk matching is an automated process that matches your salesforce records to altrata this is an asynchronous process duration depends on the size of your database — 2 3 hours per 100,000 records matches are updated in three different schedulers daily job – will screen only n ew/updated records weekly job – will screen only no match records monthly job – will screen only matched records do not run bulk matching until field mapping is fully configured this is your last chance to catch missing fields until the next bulk match run (especially the foundation brand person/org id's, if you're migrating from boardex, relsci, or wealth x) open the altrata settings tab from the app launcher click the match management tab click start matching confirm on the pop up