Appearance
Run code
When fields, formulas and the other steps can't do something, the step Run code runs PHP that you write: a code hook of the kind Automation step. It gets the record's values and returns the fields to set.
Before you start
Code hooks are on. The server's owner adds this line to .env:
iniQOREKIT_CODE_HOOKS=trueWithout it, rules with Run code can't be saved, and existing ones fail at that step.
You are a super admin. Only super admins write code hooks and put Run code in a rule; for others, the step is not in the Add a step menu. A rule that runs code is theirs alone to change, turn on or off, or delete: other administrators see "This rule runs code: only a super admin can change it."
The probability of a deal, worked out in PHP
When a deal's stage changes, a hook sets its probability from a table of its own. (A rule with Set fields could do this one; a hook can do whatever PHP can, such as asking another service or reading other records.)
The hook
Open Administration › Code hooks and click New hook.
Name:
Probability from stage. Key:probability_from_stage(it can't change later).Kind: Automation step. Entity: Deals.
Code, the inside of a function that gets
$hook:php// A choice is read as id, key, label and color: its key says which. $byStage = [ 'lead' => 10, 'qualified' => 25, 'proposal' => 50, 'negotiation' => 75, 'won' => 100, 'lost' => 0, ]; $stage = $hook->value('stage')['key'] ?? null; return ['probability' => $byStage[$stage] ?? null];Type Your password and click Save. A line with a mistake is named when you save.
The hook returns the fields to set, by field key. Keys that are not fields of the record, or that a rule can't set (formulas, files), are left out; the run says which.
The rule
- Administration › Automation, Entity: Deals, Add a rule.
- Name:
Probability from stage. - When: A record is changed, only when Stage changes.
- Add a step: Run code. Code hook: Probability from stage. The list holds the hooks of the kind Automation step made for this entity.
- Save the rule.
Try it. Change a deal's stage to Proposal: its probability becomes 50. The run, in the Runs tab, names the fields the code set.
What the hook gets
$hook->value('key'), $hook->values() | The record's values, as the REST API reads them |
$hook->input()['record_id'] | The record's id |
$hook->input()['form'] | For a rule run by a button: what its form got, by input key ($hook->input()['form']['reason']) |
$hook->user() | Whoever set the rule off: id, name and email |
$hook->records() | Records of any entity, to find, list, create and update |
$hook->http() | Requests to other services, with a time limit |
The full list is in Code hooks.
When the code fails
If the code throws an error, the step fails with its message ("The code hook failed: …"), and the run is tried again after 1, 5 and 15 minutes, as for any failed step. Fix the hook, then open the run in the Runs tab and click Try again from the step that failed.
The code runs with Qorekit's own rights
A hook can read and change every record, whatever the roles say. Your password is asked for every change, and every change is kept in the audit log, code and all.