Syncing users from Google Workspace into PaperCut Hive and Pocket

Syncing from Google Workspace allows you to do the following:

Connect PaperCut Hive or Pocket to your identity provider, ensuring that your user list is always up-to-date and matches your source of truth.
Automatically add, update, and delete users and user attributes, including full name, email address, department, access codes, and access card numbers. (Note that the ability to delete users and map user attributes depends on the chosen sync method.)
Start using custom Groups to manage your users in PaperCut Hive or Pocket. Note that custom groups are only available when users are synced via the User and group sync feature. Other methods of adding users, such as by email address or a user sync add-on, are not compatible with custom groups.

There are two options for syncing from Google Workspace:

Recommended: Via User and group sync in the admin console — a full-featured, API-based sync allowing user provisioning/deletion, user attribute mapping, and enabling the Groups functionality in PaperCut Hive and Pocket.
Google Workspace User Sync Add-on (certified app) — the classic add-on allowing user provisioning/deletion. Does not support the Groups functionality.

For most organizations, User and group sync is the best choice, particularly because it allows Groups to be enabled in PaperCut Hive and Pocket. However, the add-on might still be best suited for some long-term organizations already using the add-on versions.

How to set up “User and group sync” for Google Workspace

User and group sync page in PaperCut Hive and Pocket — The User and group sync feature of PaperCut Hive and Pocket.

Prerequisites

Before setting up User and group sync, there are a few related settings to check first:

Check your PaperCut Hive or Pocket access code default format. New users without synced access code attributes will receive an access code according to this setting.
Enable Cost Tracking in PaperCut Hive or Pocket if you want to track costs-per-page or use features like quotas and restricting user accounts. Ensure you have set up at least one Cost Profile.
Check your authentication settings in PaperCut Hive or Pocket, and ensure that your users are able to log in. Note that syncing from an identity provider does not enable Single Sign-on or social login (OAuth) from the same identity provider. Authentication methods like these are enabled separately.
Also consider any other methods used to add users to PaperCut Hive and Pocket:
- If you are using an existing user sync add-on for the same identity provider, the two syncs will sequentially overwrite each other. We strongly recommend only using User and group sync or a user sync add-on — not both. If you are currently using a user sync add-on and want to change to User and group sync, first disconnect the user sync add-on. When the user sync add-on is disconnected, your users will remain in PaperCut Hive or Pocket.
- Be aware that importing users (or user data) via the User data import tool (CSV or TSV file import) will do a one-time override of synced data. Subsequent syncs will overwrite user data where user attributes are mapped.
If necessary, complete any tidying of data in your identity provider tenant, for example, optionally creating a “Print Users” group, or ensuring users have correct group memberships of existing groups.

Identity provider attributes overview

Part of syncing an identity provider is mapping its attributes to PaperCut Hive or Pocket attributes. At a minimum, Email and Username must be mapped; all other attributes are optional.

If you store sensitive data, such as access card numbers and access codes, in another system, it can also be imported into PaperCut Hive or Pocket via the User data import tool (CSV).

Editing attributes — Google Workspace

If syncing custom data from Google Workspace, one option is to use your existing custom field or attributes in the attribute mapping. When using a multi-value field, only the first value is imported.

Scenario: In a user’s PaperCut Hive and Pocket profile, by default, the Google Workspace “organizations[].department” string is mapped to the Department field. An organization prefers to display the user’s cost center.
Solution: Delete the “organizations[].department” string, and add “organizations[].costCenter”.
Advanced scenario: An organization stores user swipe card numbers in a custom category called “Cards” with a custom field called “cardNumber”. It wants to map them to the “Card number 1” field in their sync configuration’s attribute mapping in PaperCut Hive and Pocket.
Solution: There is no default value to delete, so the organization simply adds a “customSchemas.Cards.cardNumber” string to the “Card number 1” field in the attribute mapping.

To find potential attributes, review the Google Workspace REST resources: users documentation.

How to set up a User and group sync identity provider configuration

Each PaperCut Hive or Pocket organization can have up to five identity provider sync configurations. Here’s how to set up a sync configuration:

Log in to the PaperCut Hive or Pocket admin console. Ensure you are also an administrator with all the required permissions to your organization’s identity provider tenant.
In the left navigation bar, select Settings. The Settings page is displayed.
Select the User and group sync tab. The User and group sync page is displayed.

Tip

If you're opening this page for the first time, you'll see the “Before you sync…” information. Ensure you review the related features and make any required changes.
Select Add sync configuration. The Select identity provider popup is displayed.
Select Google Workspace. The Add sync configuration page is displayed.
Select Authorize connection. A popup is displayed.
Select Continue, then follow the prompts to authorize the connection between your identity provider tenant and PaperCut Hive or Pocket. After authorization has finished you’ll see a success message on the Add sync configuration page.

Warning

Ensure the authorized account has all the required administrator access to your Identity Provider tenant. Lower-level accounts can't authorize the connection between an Identity Provider and PaperCut Hive or Pocket.

Note

You can't revoke authorization of an Identity Provider within the PaperCut Hive or Pocket admin console. If you need to revoke authorization, please revoke it from within your Identity Provider tenant.
In the Name field, enter a name for this identity provider configuration. This name is used to recognize the identity configuration in PaperCut Hive or Pocket, and is especially helpful if you have multiple sync configurations.
In User source, select which users to sync into PaperCut Hive or Pocket:
- Sync all users: every user in your connected identity provider is synced.
- Only sync users from specific organizational units: allows you to sync multiple, large organizational units of users (for example, “All print users”, “All staff”, or “All students”). Select the organizational units from the Organizational units dropdown.
  
  Tip
  
  Try to only select large organizational units (OUs) of users. Selecting lower-level OUs increases the likelihood that the same user is synced multiple times. There is no need to select fine-grained groups for policy and permission management at this stage.
  Note
  Identity Provider groups and organizational units (OUs) are used in two separate ways in two separate places in PaperCut Hive and Pocket:
  - In Sync configuration > User source, OUs are used to decide which users/data enter PaperCut Hive or Pocket via sync.
  - In Groups > Add group, groups are used to bulk manage policies and permissions for users based on their group membership in your identity provider.
  You don't need to use the same groups/OUs in both places. Most organizations use 1 to 3 groups as user sources (for example, “All staff” and “All students”), and might use additional, more fine-grained groups for policy and permission management (for example, “Year 8”, “Year 9”, etc.).
In Suspended user accounts, select whether or not you want users with suspended accounts in Google Workspace to be included during a sync (that is, synced into PaperCut Hive or Pocket). Note that users with suspended accounts who are synced into PaperCut Hive or Pocket can’t log in, or use functions such as printing — but they still appear in your Users page.
In User attribute mapping, select Edit attribute mapping. The attribute mapping popup is displayed. To learn about attributes, see Identity provider attributes overview.
Review the Google Workspace attribute column, and enter, edit, or delete attributes in the fields. Use the attribute strings from your identity provider tenant to add or edit these user data types into PaperCut Hive or Pocket during a sync. Select Apply to return to the main sync configuration editor.

Map user attributes (user data) to users to import or update the data during a sync
In Email invitation for new users, select an invitation setting for any new users that are created during a sync:
- Don’t send invitation emails automatically (for example, invite later)
- Email a link to the User Portal (user self-service)
- Email a classic invitation (no log in, for example, for guests)
Users are notified of access code updates

Whenever a user's access code is updated, including via a sync, the user is notified via email. The email type is controlled by the setting in Email Print & Scan > User Invites > Default manual invitation email.
In Sync frequency, select how and how often PaperCut Hive or Pocket will sync with your identity provider.
- Manual: No automatic or scheduled syncing occurs. Syncs must be initiated in the admin console > User and group sync > Sync now.
- Scheduled: PaperCut Hive or Pocket will sync with your identity provider on a regular schedule. Use the Frequency drop-down to select Weekly or Monthly.
  
  Tip
  
  At any time, you can immediately sync PaperCut Hive or Pocket with your identity provider. On the User and Group sync page, simply select Sync now for the configuration you want to sync.
Select Save. Your sync configuration is now displayed on the User and group sync page.
If you want to immediately start the sync, select Sync now.

Note

Syncs can take a while to process. To find out if a sync has finished, go to Logs > Activity Log and locate the log entry related to the sync. This also includes any related information (for example, errors).

Note

New users added during a sync will receive email invitations — either the classic email invitation or the User Portal invitation, (as per your organization’s setting in Easy Print & Scan > User Invites > Automatic invitation email).
If you've chosen not to send invitation emails, ensure your users are invited later.

Log records for User and group sync — Check Logs > Activity Log for entries related to a sync

How to set up the User Sync Add-on for Google Workspace

If Google Workspace is your Identity Provider (IDP), you can sync users’ access codes and/or swipe card (access card) numbers from Google Workspace into PaperCut Hive via a User Sync Add-on. This lets you keep Google Workspace as your single source of truth for this data and send any Google Workspace updates directly to PaperCut Hive.

There are two ways to sync between Google Workspace and PaperCut Hive via User Sync Add-on:

Automatically: PaperCut Hive monitors your Google Workspace and immediately syncs any changes to access codes and/or access card (swipe card) numbers.
Manually: Sync whenever you choose to.

Can a Google Workspace user immediately use their synced access code or card?

After syncing with Google Workspace, new users will automatically receive an email with setup instructions. If an access card and/or access code have been synced into PaperCut Hive, the users are sent the same details. For more information about the email, see User Portal and Classic email invitation — overview.

If an access card and/or access code have been synced into PaperCut Hive, the users are sent the same details. Please note the email received by the user is determined

Users will be able to use this access code or registered swipe card to begin printing.

Getting started

This video summarizes how to set up syncing. All the detailed steps are further down on this page.

In addition to the above video, each step is detailed below.

Step 1. Create a custom attribute and up to two custom fields in Google Workspace

Start by setting up the access card numbers and/or individual access codes in Google Workspace.

Log in to admin.google.com as an admin.
Navigate to Directory > Users.
In the list header, click the More options dropdown.
Select Manage custom attributes.
At the top right, click ADD CUSTOM ATTRIBUTE. The Add custom fields modal is displayed.

Important — you can't rename custom attributes

When adding custom categories and fields in Google Workspace, ensure you use the exact spelling, capitalization, and spacing of the Category and Custom Field names shown in the instructions below.
If you add a custom attribute with an incorrect name, you cannot update the name. You must delete the attribute and create a new one with the correct name. This is a Google Workspace limitation. For more information, see Manage Custom User Fields in the Google Workspace documentation.
In the Add custom fields section, in Category field type: PaperCut
Set up the cardNumber field. In the first row under Custom fields:
1. In the Name field, type cardNumber
2. In the Info type dropdown, select: Text
3. In the Visibility dropdown, select: Visible to user and admin
4. In the No. of values dropdown, select: Single value
Set up the accessCode field. In the second row under Custom fields:
1. In the Name field type: accessCode
2. In the Info type dropdown, select: Text
3. In the Visibility dropdown, select: Visible to user and admin
4. In the No. of values dropdown, select: Single value
Click Add. The user accounts now have and addition attribute, PaperCut, with two fields, cardNumber and accessCode, that you can populate with your values.

Step 2. Add users’ access card numbers and/or access codes into their Google Workspace profiles

You can populate one or both of the fields, either manually or in bulk.

Manually: see Google's Create custom attributes for user profiles page and scroll down to Add values to custom attributes.
In bulk: see Google's Add or update multiple users from a CSV file page.

Step 3. Add the Google Workspace Add-on to PaperCut Hive or Pocket

Log in to the PaperCut Hive admin console.
Click the Add-ons tab and select Google Workplace User Sync.
Click Add and follow the setup guidance to add the add-on.

Step 4. Sync with Google Workspace

You can set up automatic or manual syncing.

Automatic syncing

Each time the Google Workspace User Sync Add-on syncs with PaperCut Hive, the values set for cardNumber and accessCode will show up in the matching user’s profile in PaperCut Hive. If the user has already set up printing with PaperCut Hive, they can simply start releasing print jobs with their access card (swipe card) straight away.

In the Add-ons page, on the Google Worskspace User Sync card click Manage.
Click the Configuration tab.
For Sync mode, select Automatic.
In the Sync source dropdown, select All Users or Selected Organizational Units (depending on how your Google Workspace is set up).
(Optional) If you're only syncing specific Organizational Units, in the Org Units dropdown select the relevant units.
(Optional) If you’d like to automatically delete users in PaperCut Hive when they’ve been deleted in your Google Workspace, select the Automatically delete users who are removed from the sync source checkbox.
Click Save and sync to start syncing. You can see new users and details in the Users page.

Manual syncing

In the Add-ons page, on the Google Worskspace User Sync card click Manage.
Select the Manual tab and click Save and sync.

Migrating from a user sync Add-on to User and group sync

It’s possible to migrate from a user sync Add-on to User and group sync. Organizations that previously used the Google Workspace user sync Add-on should disconnect the Add-on, and set up a sync configuration in User and group sync.