Establishing VPA Groups

If you turn on the VPA Groups feature, the Web Central program changes the way it defines VPA restrictions. More specifically, the program:

Does not use the Archibus User table's Building Code List (afm_users.bl_id_list) or Site Code List (afm_users.site_id_list).
Does not use the Archibus Roles table's VPA Restriction (afm_roles.vpa_restriction)

Instead, the program builds restrictions for all roles from the VPA Restrictions (vpa_rest) table. Most of these restrictions rely on VPA Groups – groups of restrictions based on mapping tables.

The VPA Groups application preference

This preference specifies whether the program should use the VPA Groups feature. It is 0 by default, and it is also 0 if this Application Preference (afm_activity_params) record does not exist.

Application	Parameter	Value	Description
AbSystemAdministration	UseVpaGroups	1	1 if the program is to use the VPA Groups feature; 0 otherwise.

The VPA Restrictions (vpa_rest) table

The VPA Restrictions table contains a list of restriction definitions that the program applies to the given table and to all validated tables.

Specifically, for each record in the VPA Restrictions table, the program adds a restriction:

to the last primary key field of the specified table (for example, bl.bl_id)
to all fields that validate on this table (fior example, eq.bl_id, mo.bl_id_from)

A typical set of VPA Restriction records is:

Validating Table Name	Type
bl	VPA Groups
legal	VPA Groups
eq	VPA Groups

You can also specify a role for each vpa_rest record. If you do, that particular VPA restriction is added only to that role.

The VPA Groups (vpa_groups) table

This table lists the different groupings of restrictions. This table is used as a validating table for:

assigning VPA Groups to users or roles
assigning specific records to access – such as building records – to one of these VPA Groups.

These VPA Groups have no other deeper functionality than to act as a validating table for VPA Group ID names.

For example:

VPA Group ID	Description
REGN-EAST	East Coast Locations
REGN-WEST	West Coast Locations

Typical mapping table

Mapping tables hold lists of values grouped by VPA Group. A typical mapping table is the VPA Mapping Table for Buildings (vpa_bl), shown below. VPA Restrictions refer to these lists when assembling restrictions.

VPA Group ID	Building Code
REGN-EAST	HQ
REGN-EAST	SRL
REGN-EAST	BOSMED
REGN-EAST	JFK-A
REGN-WEST	LA-OFFICE
REGN-WEST	SF-OFFICE
REGN-WEST	OAK-WARE

Types of VPA restrictions

You can specify two types of restrictions using a VPA Restriction record:

VPA Restriction Type

Description

VPA Groups

The program generates a restriction on the VPA Groups mapping tables.

See Assigning VPA Groups Using Mapping Tables for the format of the query.

Explicit Query

You specify the subquery yourself. This subquery can refer to macros that make the query generic for all related tables and for all users.

The table below lists multiple restrictions for the "bl" table by way of example. However, in deployment you can only have one restriction per table.

Example	Type	Validating Table Name	Role Name	Subquery
Build a SELECT subquery on groups	VPA Groups	bl
Use literal SQL (without referring to a VPA mapping table)	Explicit Query	bl		${sql.mainTable}.bl_id LIKE "JFK%"

For each restriction, the program creates a WHERE clause that can be applied to the given table or to a table that validates against it. When forming a datasource, the program applies this restriction.

Note: The feature essentially is an easier way of creating forValidatedTables restriction. It creates one such restriction for each row. See VPA Restrictions entered in the A/FM Roles table .

Binding expressions

The VPA Restrictions depend on several server-side binding expressions that the program evaluates when applying the restriction to the datasource.

Expression	Example Value	Description
${sql.mainTable}	eq	Evaluates to the name of the main table in the current DataSource.
${user.name}	ABERNATHY	Evaluates to the login name of the current user.
${user.legalId}	BSC	Identifier for this customer's organization (the legal entity that is their employer) that is entered in the Users account record (their `afm_users.legal_id` value).
${user.option1} ${user.option2} ${user.option3} ${user.option4}	BOS-SERVCONT	Evaluates to the value of the Option1, Option2, Option3, or Option4 field of the Archibus Users table. These fields are largely replaced by VPA Groups and mapping tables – since the lists of buildings, equipment, and other items are more easily managed in centralized lists that multiple users can share. These fields are still useful for adding any hard partition restrictions you might need in addition to the Legal ID restriction.
${user.role}	SPACE	Evaluates to the Archibus Users "primary" or first role value `(afm_users.role_id`). This value is used in application logic such as help desk requests, work request routing, reservations approvals, which currently use this macro or hard-code references to the `afm_roleprocs` table.

While the options above are most typical, you can use any server-side binding in VPA restrictions. See:

VPA restrictions in SQL queries

Some views use SQL queries directly. The program cannot apply the VPA restriction to these queries directly. However, you can add the VPA restriction to their queries using these binding expressions.

Expression	Description
${sql.vpaRestriction}	Generates SQL WHERE clause from VPAs for current user/role applicable to the main table in current DataSource.
${sql.getVpaRestrictionForTable('table')}	Generates SQL WHERE clause from VPAs for current user/role applicable to the specified table in current DataSource. table - name of main or standard table in the current DataSource for which to generate SQL.
${sql.getVpaRestrictionForTableAndRole('table','role')}	Generates SQL WHERE clause from VPAs applicable to the specified table in current DataSource. The role will be used by `forVpaGroups` VPAs (if current user/role has such restrictions) to generate "EXISTS (SELECT ...)" to restrict table using mapping tables; otherwise it will be ignored. This expression is useful for system WFRs that must suspend the user's VPA (for example, a room reservation query that can see all conference rooms in the campus even if the user doesn't have VPA access to all rooms). Example: `${sql.getVpaRestrictionForTableAndRole('rm','Reservation User'}` This expression enables you to add roles and VPAs that the you can manage centrally but that application code can use to get access to specific groups of records as part of specific features (e.g. Room reservations). The Admin assigns any needed VPA Group permissions to the role; this expression then creates an SQL statement that references those VPA groups. table - name of main or standard table in the current DataSource for which to generate role - name of user role.
${sql.getVpaGroupsRestrictionForBridgeTable(table, bridgeTable)}	Generates "EXISTS (SELECT ...)" to restrict table using mapping tables `vpa_groupstoroles`, `vpa_groupstousers`, `vpa_[bridgeTable]` for the current user and role. table - name of table to which access should be restricted. bridgeTable - name of bridge table. The bridge table has to be referenced in foreign key of table.
${sql.getVpaGroupsRestrictionForMappingTable(table, vpaMappingTable, fieldName)}	Generates "EXISTS (SELECT ...)" to restrict table using mapping tables `vpa_groupstoroles`, `vpa_groupstousers`, `vpaMappingTable` for the current user and role. table - name of table to which access should be restricted. vpaMappingTable - name of VPA mapping table. fieldName - name of field in table and in vpaMappingTable.

Here is an example from \schema\ab-products\asset\eam\common\filters\ab-eam-project-filter.axvw:of using these binding expressions in a personalized SQL query.