New data storage model

Workbench Access has undergone some major changes between the 8.x-1.0 alpha version and the 8.x-1.0 beta release.

If you have developed a custom module around the API as it stood in any alpha version, you may need to update your code to use the newest APIs. You may also need to implement an update hook to preserve data storage.

Site Builders and Maintainers

The underlying changes to the module have been captured in update hooks. When upgrading to beta1, you should follow these steps:

• Make a backup of your site's database and code.
• Note your current section assignments for editors and roles.
• Login as the administrative user.
• Place the site into maintenance mode.
• Update the module code (using your preferred method).
• Run the database upgrades, either via drush drush updb --entity-updates or via the browser at update.php.
• Take the site out of maintenance mode.

Things to check to ensure that the upgrade was successful.

• The field 'field_workbench_access' should no longer be present on user accounts. See the list at /admin/config/people/accounts/fields.
• Your section assignments for editors and roles should be preserved. Check those at /admin/config/workflow/workbench_access by clicking the Sections button.
• If you have created any custom Views that use Workbench Access information, you may need to update those to use the new field options. That process cannot be automated.

If these items are not correct, you may wish to restore from backup and revert to the older version of the code. In that event, please file an issue that states:

• What version of Drupal you are running.
• What module version you upgraded from.
• What access scheme types you are using.
• What upgrade failures you experienced -- what did you expect? what actually happened?

New Permissions

A new permission has been added Assign users to selected Workbench Access sections both this permission and Assign users to Workbench Access sections give access to the new account tab labelled 'Workbench Access'.

On this tab, the section assignments for individual users may be managed. What is visible on the form depends on the permission level of the account making the edits.

• Assign users to Workbench Access sections -- will be allowed to see and assign all sections in all access schemes.
• Assign users to selected Workbench Access sections -- will be allowed to see and assign only to sections (and their children) that the editing account is also assigned to.

This change allows site administrators to allow other users to add members to sections without giving them access to edit user accounts or to administer Workbench Access settings.

Developers

The following changes have been introduced in beta1. (Additionally. there were a code-level changes made in alpha7 that you should review.)

Update Hooks

If you have created a module that implements the AccessControlHierarchy plugin class, you are responsible for creating an upgrade path for the configuration of that plugin.

There are three parts to that upgrade:

1. Implement the defaultConfiguration() method.
2. Implement the new buildConfigurationForm() method in order to register with the main module's configuration form.
3. Implement the submitConfigurationForm() method.
4. (Optional) Implement the validateConfigurationForm() method.

After implementing these methods, you need to provide an update hook to convert from Drupal's state storage to the new configuration storage.

/**
 * Converts scheme settings to use the AccessScheme entity type.
 *
 * @param array $settings
 *   An array of settings for the plugin. Likely empty. Be certain to only act
 *   on your plugin scheme.
 *
 * @param Drupal\Core\Config\Config $config
 *   Current data object for Workbench Access configuration.
 *
 * @return
 *   No return value. Modify $settings by reference to match the array defined
 *   by your plugin's implementation of
 *   AccessControlHierarchyInterface::defaultConfiguration().
 */
function hook_workbench_access_scheme_update_alter(array &$settings, Drupal\Core\Config\Config $config) {
  if ($config->get('scheme') === 'my_plugin_scheme') {
    $fields = [];
    foreach ($config->get('fields') as $entity_type => $field_info) {
      foreach (array_filter($field_info) as $bundle => $field_name) {
        $fields[] = [
          'entity_type' => $entity_type,
          'bundle' => $bundle,
          'field' => $field_name,
        ];
      }
    }
    $settings = [
      'my_scheme_type' => array_values($config->get('parents')),
      'fields' => $fields,
    ];
  }
}

The values in the $settings array should map to those in defaultConfiguration().

See workbench_access_post_update_convert_to_scheme() in the workbench_access.post_update.php file for the implementation.

API changes

UserSectionStorage

The method signatures for UserSectionStorage::addUser have changed to pass the full Account object from the caller.

Before:

public function addUser(AccessSchemeInterface $scheme, $user_id, array $sections = [])

After:

public function addUser(AccessSchemeInterface $scheme, AccountInterface $account, array $sections = [])

The method signatures for UserSectionStorage::removeUser have changed to pass the full Account object from the caller.

Before:

function removeUser(AccessSchemeInterface $scheme, $user_id, array $sections = [])

After:

public function removeUser(AccessSchemeInterface $scheme, AccountInterface $account, array $sections = [])

Both of these methods now return a fully loaded User object.

AccessControlHierarchy

In addition to the new form and configuration handling, we also can track dependencies and changes by implementing the methods calculateDependencies() and onDependencyRemoval(array $dependencies).

These methods are used to track entity type and bundle settings changes that may affect your plugin. See the examples in Menu.php and Taxonomy.php for details.

Data storage

The module now uses a Section association entity to store information about user and role assignment. This change should be fairly transparent to most modules that are using the APIs.

Section association data is not directly accessible from the user interface. The current section assignment forms are retained, and individual user forms have been added as tabs on the account page.

Section associations are available to Views, and can be used with user and other entity Views or as stand-alone Views based on the section association entity.

Section association storage can be accessed like any entity, using the EntityTypeManager class: \Drupal::entityTypeManager()->getStorage('section_association'). There is one helper method on this storage class, loadSection($access_scheme_id, $section_id), which will return scheme information for a specific section.

For most uses, third-party code will not interact with section associations directly. Use the UserSectionStorage and RoleSectionStorage service classes instead.