Forms
Set a form’s customer-portal visibility
/a/Form_setPortalVisibility
Configure whether jobs using the form are visible and whether the form is selectable in customer-portal workflows.
When to use this endpoint
Configure whether jobs using the form are visible and whether the form is selectable in customer-portal workflows. This does not grant a customer access to unrelated records.
Use a form ID supplied by the Forms list. Read the current definition before making a narrowly scoped change; this endpoint does not save questions, report templates or existing job answers.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. The signed key acts as its associated tenant user.
Existing-definition settings writes require Forms Edit (pageForms_edit); client administrators pass the standard permission helper. Roleless/non-edit users fail closed. Temporary setup accounts retain their provisioned Forms Edit permission; the metadata marker alone does not grant that permission.
The account features2.disableFormEdits=1 setting blocks definition writes, except temporary setup users. Writes stay in the authenticated tenant; they do not modify an outsourced source definition.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible form ID | Yes | Required and truthy before integer conversion. Missing/null/blank/zero gives the ID error; a truthy malformed value can convert to zero and then fail the row lookup. |
val | Scalar value | Yes | Non-null value for portal_visibility. No trimming or allowed-value validation; zero and blank are accepted. Use 0, 1 or 3 in ordinary portal flows. |
Example request
$result = FM_api('Form_setPortalVisibility', [
'id' => '1042',
'val' => '3',
]);Example response
{
"ok": 1
}The changed response is ok=1. An unchanged flag adds the warning described below.
Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error":"form edits are disabled for this account"} | Account disableFormEdits is 1 and the actor is not a temporary setup user. |
{"error":"no ID provided"} | The ID is absent or false-like. |
{"error":"no val provided"} | val is absent/null. |
{"error":"form does not exist"} | No row for the integer-converted ID, or the initial lookup fails. |
{"error":"permission denied"} | The actor lacks Forms Edit. Client administrators pass the standard permission helper; the temporary marker alone grants no access. |
{"error":"Unable to save form settings. Check the saved state before retrying."} | A read, primary write, history, undo or transaction acknowledgement failed; do not replay an uncertain save without refreshing. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Normal values are 0=not visible/selectable, 1=visible, 3=visible and selectable. Portal job lists test bit 1; portal form pickers use exact values 1 or 3 and require active Job forms. The RPC does not enforce these valid combinations.
- Requires an existing local form, including an archived one. There is no form-type restriction, active/deleted filter, owner check or automatic migration of saved job answers.
- The supplied value is written as quoted text without a boolean/bitmask allowlist. Normal clients send the values described below; arbitrary non-null text is not validated by this handler. The database column’s conversion/range rules still apply.
- An unchanged value returns {"ok":1,"warning":"value already set"} before update, history or undo creation.
- On change, locks the existing row and saves the setting, last_edited, attributed history and an after-change undo snapshot in one checked tenant transaction. Nested callers retain their transaction through a savepoint. Failed data/history/undo operations roll back; uncertain commits are not automatically replayed.
- No direct mobile app/m-service caller for this RPC was found. Mobile form definitions are downloaded through m’s syncDownloads form channel rather than these CRM calls.
Side effects
- Updates forms.portal_visibility and last_edited, invalidates forms cache, records attributed form/portal_visibility, inserts a full after-change row snapshot into undos, and commits all three together. A no-op skips these effects. No email, job event or inventory transaction is invoked.
See it in Fieldmotion
CRM1
Open Forms and change the Portal Visible/Pickable cell. Filter Network for Form_setPortalVisibility; the caller sends val.
CRM2
Forms exposes the Portal Visible/Pickable setting through its mapped editor. No direct Form_setPortalVisibility caller was found; the standard editor uses Form_updateData/Form_updateField rather than this dedicated setter.
Related endpoints
Form_getreads the stored definition.Forms_getByIdretrieves selected raw columns in a batch.