AI scoring rates Lead and Opportunity records from 0 to 100, with a label, a written reason and a recommendation. The score, label and reason are stored on the record and shown by the aiScoreCard component; the recommendation is shown on the card right after scoring and is not stored. This article covers the admin configuration on the AI Scoring tab. For what users see, see AI Score card.
Before you start#
- An AI provider is connected and working. See Connect your AI provider.
- You need the
AI_Engine_Adminpermission set. Score All … Now and scheduled batches score the records as you, so you also needAI_Engine_User. - Users who view or trigger scores need
AI_Engine_User, which also grants access to the score fields. - Add
aiScoreCardto the Lead and Opportunity record pages in Lightning App Builder. See Add components to pages.
Where results are stored#
| Field | Content |
|---|---|
AI_Score__c |
The score, 0 to 100 |
AI_Score_Label__c |
The label, for example Hot, Warm or Cold |
AI_Score_Reason__c |
The written reason |
AI_Score_Date__c |
When the record was last scored |
You can use these fields in list views, reports and flows like any other field.
Step 1: Activate scoring for an object#
- Open Ai Agent Admin Setup → AI Scoring.
- Select Lead or Opportunity. Each object has its own configuration.
- Switch Scoring Active on.
- Configure the sections below, then click ✓ Save Scoring Config at the bottom.
Once a configuration is saved with Scoring Active off, scoring requests for that object return "Scoring is not active for Lead." (or Opportunity) instead of a score, and automatic and scheduled scoring do not run.
Step 2: Decide what the AI sees#
Scoring Context Fields sets exactly which fields of the record are sent for scoring. This is the most important scoring setting. See Scoring context fields.
Step 3: Historical pattern (won/lost)#
The AI compares each record with your recent won and lost records.
| Setting | Meaning |
|---|---|
| Compare Against Object | Where the history comes from: Opportunity or Lead. Select the object from the list even if the one you want is already shown, so that it is saved. If no object is saved here, the history step is skipped |
| Won/Lost Field | The field that holds the outcome, for example StageName or Status |
| Won Value / Lost Value | The values that mean won and lost, for example "Closed Won" and "Closed Lost" |
| Sample Size | How many of the most recently modified won and lost records are read, from 10 to 100. Default 30 |
Up to 15 won and 15 lost examples go into each scoring request. If there are no won or lost records yet, this part is skipped. Scoring quality depends on having a real history, so tell users this before go-live in a new org.
Step 4: Your own rules (optional)#
- Scoring Instructions — Custom Criteria. Plain-language rules the AI must follow: what a good lead looks like, what to exclude, score bands and label names. For example: "Free-mail address with no company name = Junk, score 0–10." Labels you define here replace the default labels; a label longer than 40 characters is replaced by the default label for the score.
- Output Language. The language of the written reason and recommendation. Options: Org default (English), User language (the language of the user who triggers scoring; for a scheduled batch, the user who activated the job; English if that language is not one of the fixed options), or a fixed language: English, Polish, German, Dutch, French, Spanish, Italian. Labels are not translated.
- Field Weights — Scoring Signals. Click + Add Weight Rule, pick a field, enter the points and, optionally, a condition such as
= Webor!= null. Each rule is passed to the AI as a signal, for example "Lead Source: +20 points when = Web". The AI applies the weights on top of its own analysis. Rules with 0 points are ignored. You can also write weights into the instructions, for example: "Lead Source = Web adds about 20 points."
Without your own labels, the defaults are Hot (70–100), Warm (40–69) and Cold (0–39).
Limit which records are scored#
Filter — Which Records to Auto-Score takes up to three conditions (field, operator, value). Only records that match all of them are scored by automatic scoring, the scheduled batch and ▶ Score All … Now. Leave it empty to score all records. Use it to keep cost down, for example by excluding closed or converted records. Scoring from the AI Score card is not filtered.
Step 5: Choose when scoring runs#
| Trigger | How it works |
|---|---|
| Score New Records Automatically | Scores each new record shortly after it is created. |
| Auto-Refresh Enabled (card Auto-Refresh Score) | Re-scores a record when it is updated. In Refresh When Field Changes, which appears when the switch is on, you can limit this to changes of specific fields: enter their API names separated by commas. See the note below. Leave the field empty to re-score on any update. |
| ▶ Score All Leads Now (the same button on Opportunity) | Scores up to 200 records per click, in the background, using the last saved configuration, so save first. Records that already have a score are skipped unless you tick Re-score already scored records, so another click scores the next 200 unscored records. With the box ticked, each click takes up to 200 records whether or not they were just scored, so repeated clicks do not work through a larger set in turn. |
| Scheduled Batch | Runs the same batch on a schedule. See below. |
| On the record | Users click Generate AI Score or the recalculate icon on the AI Score card. |
Refresh When Field Changes reacts only to these fields: Lead Status, Rating, LeadSource and Industry; Opportunity StageName, Amount, CloseDate and Probability. Other field names in the list never trigger a re-score.
Automatic scoring runs only for changes made by users who hold AI_Engine_User. Changes by integration users without that permission set do not start scoring.
Schedule a batch#
- Switch Scheduled Batch on.
- In Batch Frequency, select Daily, Weekly or Monthly. For Daily and Weekly, also select the hour, and for Weekly the day. Monthly runs on the 1st of the month at 02:00. Select each value from its list even if the one you want is already shown.
- Click ✓ Save Scoring Config.
- In Scheduled Job Status, check that the button shows the frequency you chose, for example ▶ Activate (daily), and click it. The job takes the frequency, day and hour selected in the form at that moment, so do steps 2 to 4 in one go.
- The status changes to ✓ Job Active and shows the next run. Check that the time is the one you expect: Salesforce runs a scheduled job in the time zone of the user who activates it, which can differ from the time zone shown next to the hour.
Each scheduled run scores up to 200 records that do not have a score yet. The job runs as the admin who activated it, so that user must keep both the AI_Engine_Admin and the AI_Engine_User permission sets. To change the schedule, click Stop Job, change the settings and activate again.
Cost#
Each scored record is one AI request, and Verify Company On The Web adds one more. Automatic scoring on busy objects can add up, especially Auto-Refresh with no field list, which re-scores on every update. Start with the batch button, check cost in the Activity Monitor, then switch on automatic triggers.
Troubleshooting#
The most common causes:
- No scores appear. Scoring Active is off, the configuration was not saved,
aiScoreCardis not on the page, or the user who ran the scoring (for a batch, you) does not haveAI_Engine_User. - "No unscored records found matching filters." The records the batch can see already have a score. To score them again, tick Re-score already scored records.
- The reason says a field is missing although the record has it. The field is not in Scoring Context Fields, or the user who ran the scoring cannot read it.
- A scheduled job seems stuck. Click Stop Job, then activate it again.