Apex API

NovigemAPI is the supported Apex entry point into the Novigem rule engine. It is a global class in the managed package, so Apex in your org or in another package can call it. It is meant for ISV partners and Apex developers who want records of their own objects scored by Novigem rules.

In a subscriber org the class carries the package namespace: ngm.NovigemAPI.

When to use it

You want to	Use
Score Opportunity, Lead, Task, or Event	Nothing. Novigem’s packaged triggers already do it
Score any other object, no code	A record-triggered Flow with the Evaluate Record with Novigem action. See Gamify a new object
Score any other object from Apex, for example your own package’s trigger	`NovigemAPI.evaluate`

The Flow action calls this same method under the hood, so the engine treats both routes the same way.

Do not call it for Opportunity, Lead, Task, or Event. The packaged triggers already send every save of those objects to the engine, so your call evaluates the same save a second time. The ledger’s dedup key stops a rule paying the same user twice for the same record, but the second pass still uses governor limits.

Before it does anything

The object must be registered and enabled under Novigem Admin → Settings → General → Tracked Objects, and the rules must exist in the Rule Builder for that object. See Gamify a new object, steps 1 to 3.

The engine checks these on every call. When one fails, the call returns normally with rulesMatched = 0 and no error:

Enable Rule Engine is off
The object is not enabled under Tracked Objects
The running user (the one who saved the record) has no Novigem licence
The running user has no read access to Rules (Rule__c), usually because they have neither the Novigem User nor the Novigem Admin permission set
The engine is already running in this transaction, for example when your trigger fires because of a write the engine itself made

Integration users are the common surprise. If your integration user saves the records and has no Novigem licence, every save is skipped silently. The user who earns the points must also hold a licence, separately from the user who saves.

evaluate


global static EvaluationSummary evaluate(EvaluationRequest request)

Sends a set of records through the engine: condition evaluation, ledger entries, challenge progress, and completion rewards, all in the current transaction. Call it from an after insert or after update trigger, so the records have Ids.

EvaluationRequest

Field	Type	Required	Description
`records`	`List<SObject>`	Yes	The records to evaluate, for example `Trigger.new`
`oldRecords`	`Map<Id, SObject>`	For updates	Prior record state keyed by Id, for example `Trigger.oldMap`. Leave null for inserts. Without it, change-detection conditions (`isChanged`) cannot see the old value
`objectApiName`	`String`	Yes	API name of the object, for example `Case` or `acme__Patient__c`
`operation`	`String`	Yes	`NovigemAPI.OPERATION_INSERT` or `NovigemAPI.OPERATION_UPDATE`

Create it with the no-argument constructor new NovigemAPI.EvaluationRequest() and set the fields.

Operation constants

Constant	Value	Runs rules with Trigger Type
`NovigemAPI.OPERATION_INSERT`	`'INSERT'`	Create
`NovigemAPI.OPERATION_UPDATE`	`'UPDATE'`	Update

The operation is trimmed and matched without regard to case. 'CREATE' is also accepted as an insert.

EvaluationSummary

Field	Type	Description
`recordsProcessed`	`Integer`	Number of records submitted in the request
`rulesMatched`	`Integer`	Number of record-and-rule pairs that matched and had an eligible user to award. A match whose award was then skipped as a duplicate still counts

If request is null, or records is null or empty, evaluate returns a summary with both fields at 0 and does nothing.

NovigemApiException

NovigemAPI.NovigemApiException is a global exception, so you can catch it from another namespace. It is thrown when:

Cause	Message
`objectApiName` is blank	`EvaluationRequest.objectApiName is required.`
`records` contains a null entry	`EvaluationRequest.records must not contain null entries.`
A record has no Id (not yet saved)	`EvaluationRequest.records must contain persisted records (Id is required).`
A record is not of the type named in `objectApiName`	`EvaluationRequest.objectApiName is {name} but a record of type {type} was passed. All records must belong to the named object.`
`operation` is null or not recognised	`Unsupported operation: {value}. Use NovigemAPI.OPERATION_INSERT or NovigemAPI.OPERATION_UPDATE.`

These are checked before any rule runs, so a thrown exception means nothing was awarded. A rule that fails while it is being evaluated does not throw: that rule simply awards nothing, and the other rules carry on.

Example

A trigger on a custom object Site_Visit__c in a subscriber org:


trigger SiteVisitNovigem on Site_Visit__c (after insert, after update) {
  ngm.NovigemAPI.EvaluationRequest req = new ngm.NovigemAPI.EvaluationRequest();
  req.records = Trigger.new;
  req.oldRecords = Trigger.oldMap;
  req.objectApiName = 'Site_Visit__c';
  req.operation = Trigger.isInsert
    ? ngm.NovigemAPI.OPERATION_INSERT
    : ngm.NovigemAPI.OPERATION_UPDATE;
  ngm.NovigemAPI.evaluate(req);
}

Pass every record of the trigger in one call. The engine is bulkified, so one call per trigger is cheaper than one per record.