set_form_permissions

Set which groups can use a form, and what their members can do with it. Read the current permissions with get_form_permissions_by_group first, so you extend the arrangement already in place instead of replacing it with a different one.

Permissions come in two flavours: Access and Abilities. Access lets group members reach the form, and also makes that group count as one of “their groups”, for the purposes of the group-level abilities. Abilities are everything else: what members may do and see once they are in. Nothing works without access somewhere - a group with abilities and no access grants nothing on its own, though its abilities do apply to members who reach the form through another group.

There are three group-level abilities: view_groupscope, update_group_entries, and delete_group_entries, which let people see, update and delete entries belonging to “their groups”. Which groups are “their groups” is worked out per user: it means every group that user belongs to which also grants access to this form. Because permissions add up across all of a user’s groups, the group granting view_groupscope does not have to be one of the groups that grants access. That is what makes this arrangement possible:

All Staff grants view_groupscope but no access. HR and Legal each grant access. Someone in All Staff and HR sees entries made by HR’s members. Someone in All Staff and Legal sees entries made by Legal’s members. The scope ability lives on All Staff; what it resolves to comes from HR or Legal.

Sites are arranged in different ways and Formulize supports many possible permission configurations; there is no standard arrangement to aim for. Simple sites have a few groups each with a full set of access and abilities permissions. More complex sites could simply have more groups, or multi-level arrangements with broad groups for abilities (All Managers, All Staff, All Clients) and narrow groups for access (HR, Legal, Accounting). Work out which arrangement this form uses and extend it. Never “tidy up” a group that grants access and nothing else, or abilities and no access: both are deliberate positions.

Two permissions are always on for every group and cannot be set here: viewing the entries they made themselves, and managing their own saved views.

A group can also have visibility conditions, which restrict its members to entries matching those conditions. get_form_permissions_by_group reports them, but they cannot be set through these tools; they are configured in the Formulize admin interface. Changing a group’s permissions here leaves its conditions untouched.

Only the groups you name are changed. What you supply replaces that group’s current permissions rather than adding to them, so include everything the group should end up with.

A form can also be set to inherit its permissions from another form, in which case they are maintained on that other form and copied to this one, and this tool will refuse to change them here and tell you which form to go to instead. Setting up, changing or removing that arrangement is done with set_form_permission_inheritance.

Giving a user permission to access a form does not make it automatically show up in the menu. Just because a user has the right to use a form, that does not necessarily mean they need to see it in the menu. The user might access it through the screens of another form, for example. Don't forget to give users access to the menu items they need, using create_menu_item or update_menu_item.