Syncing users from Google Workspace

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

Prerequisites

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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. To find potential attributes, review the Google Workspace REST resources: users documentation.

• 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.

There is some additional information that’s helpful to know if your synced attribute strings include arrays:

• By index: If an attribute includes an array, for example “organizations[].department”, it is possible to specify a position within the array to import that specific user data. PaperCut Hive and Pocket uses zero-based indexing. This means that entering the value “0” in the attribute string (for example: “organizations[0].department”) will sync the user data in position 1. Similarly, entering the value “1” in the attribute string (for example: “organizations[1].department”) will sync the user data in position 2.
• By type or customType: PaperCut Hive and Pocket also support “type” and “customType” in attribute strings. For example, “externalIds[organization].value” will match the user data to the result for that specified type. The system will first seek a match for the “type”, and if one is not found, will seek a match for “customType” by default.

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:

1. 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.
2. In the left navigation bar, select Settings. The Settings page is displayed.
3. Select the User and group sync tab. The User and group sync page is displayed.

4. Select Add sync configuration. The Select identity provider popup is displayed.
5. Select Google Workspace. The Add sync configuration page is displayed.
6. Select Authorize connection. A popup is displayed.
7. 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.

8. 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.
9. 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.

10. 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.
11. In User attribute mapping, select Edit attribute mapping. The attribute mapping popup is displayed. To learn about attributes, see Identity provider attributes overview.
12. 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.
    1. In the Test attribute mapping > Email address field, enter a test email address, then select Preview. Review the results in the Preview column to check that the displayed user data matches your expectations. Make any amendments and re-test as necessary. Common warnings to troubleshoot and notes include:
       1. Invalid attribute: the mapped string is not valid.
       2. No user data found: there is no associated data for this user.
       3. Unable to preview: the user does not have this custom attribute populated in their IDP or the custom attribute string is incorrect.
       4. Ignored: attribute not mapped, and will be skipped during a sync.
       5. Auto-generated: on sync, an access code will be auto-generated for this user. This may be because, for example, the attribute is not mapped, or a valid access code string is not mapped.
       6. Required data not found: no user data exists for a required attribute. Users without required attribute will be skipped during sync.
    2. Select Apply to return to the main sync configuration editor.

13. 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)

14. 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.

15. Select Save. Your sync configuration is now displayed on the User and group sync page.
16. If you want to immediately start the sync, select Sync now.

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.

1. Log in to admin.google.com as an admin.

2. Navigate to Directory > Users.

3. In the list header, click the More options dropdown.

4. Select Manage custom attributes.

5. At the top right, click ADD CUSTOM ATTRIBUTE. The Add custom fields modal is displayed.

6. In the Add custom fields section, in  Category field type: PaperCut

7. 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

8. 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

9. 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

1. Log in to the PaperCut Hive admin console.
2. Click the Add-ons tab and select Google Workplace User Sync.
3. 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. 

1. In the Add-ons page, on the Google Worskspace User Sync card click Manage.

2. Click the Configuration tab.

3. For Sync mode, select Automatic.

4. In the Sync source dropdown, select All Users or Selected Organizational Units (depending on how your Google Workspace is set up).

5. (Optional) If you're only syncing specific Organizational Units, in the Org Units dropdown select the relevant units.

6. (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.

   

7. Click Save and sync to start syncing. You can see new users and details in the Users page.

Manual syncing

1. In the Add-ons page, on the Google Worskspace User Sync card click Manage.
2. 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.

Frequently asked questions

I already use a user sync Add-on without groups functionality. Can I use Groups in PaperCut Hive or Pocket?

Yes, but you will have to change how you sync. Groups functionality is only available when set up via Groups in the admin console and when user syncing has been set up via User & Group Sync. It is not available via a user sync add-on.

Organizations using a user sync add-on for Google Workspace must migrate to the built-in User & Group Sync before they can use groups.

Can I use a user sync Add-on at the same time as User and group sync?

No. This might cause data clashes.

Can I change from a user sync add-on to User and group sync?

Yes, you can change from a user sync add-on to User and group sync. You'll need to disconnect the user sync add-on, create a sync configuration in User and group sync, then start syncing again. Ensure you check that your sync configuration's attribute mapping is completed for all fields you want synced.

The User and group sync configuration will "take over" where your user sync add-on left off — plus you'll be able to start using the Groups feature in PaperCut Hive or Pocket.

Before migrating, organizations which previously used the Microsoft Entra ID user sync Add-on will also need to review the migration guide.

How often does PaperCut Hive or Pocket sync with my identity provider? When does the syncing start?

As part of setting up User and group sync in PaperCut Hive and Pocket, you’ll select whether you want to sync manually (ad hoc, on demand, when you press the Sync now button in the admin console) or whether you want to automatically sync on a weekly or monthly schedule.

The sync will start at the next time the schedule is triggered.

To immediately sync your sync configuration, you can always Sync now.

User restrictions and balances aren’t synced attributes, and I’m migrating from PaperCut NG/MF. How do I get these into PaperCut Hive or Pocket?

To import existing balances and restricted status against your migrated users:

1. Set up User and group sync, and complete a sync.

2. Use the Import user data (CSV) tool to export the user list from PaperCut NG/MF.

3. Re-import the CSV/TSV file containing the email, balance, and restricted status columns into PaperCut Hive or Pocket.

What happens if an error prevents PaperCut Hive or Pocket from synchronizing with my identity provider?

When a sync can't start due to an error, no changes are made to the PaperCut Hive or Pocket organization. In this situation, check the Activity Log for an error message.

If a sync fails partway through, PaperCut Hive or Pocket will attempt to process as much information as possible. Some information may not be available to process. Check the Activity Log for an error message and try re-syncing later.

If a sync fails or partially fails due to data errors (for example, multiple users with the same access code), go to the Activity Log and download the report. Review any errors in the report, amend the data in the identity provider, and sync again.

Does User and group sync support just-in-time provisioning (on demand provisioning)?

No. We may consider this in the future.

How can I test User and group sync?

1. Set up a User and group sync configuration with:
   User source: a test group/administrative unit/organizational unit with test users in it that do not already exist in your PaperCut Hive or Pocket Users list
   Sync frequency: manual.

2. Select Sync now.

3. After the sync completes, check the Activity Log for a report, and check how the users were imported into your PaperCut Hive or Pocket organization.

4. When you're ready, you can change your User source to your real users, and change your Sync frequency if desired.

If you need tips and assistance, contact your Accredited Reseller for support.

If the sync fails, what error messages will I see and where can I find them?

If a sync fails, you can view the details in Logs > Activity Log.

How do I delete users during a sync?

If you deleted users in your connected identity provider, and want those users deleted from your PaperCut Hive or Pocket Users list, perform a manual sync and choose to delete these users. Be careful — after this data has been deleted, it can't be recovered.

To perform a manual destructive sync:

1. In the admin console, go to Settings > User and group sync and locate the correct sync configuration.

2. Select Sync now.

3. In If users are deleted in the synced user source: select Delete the users in PaperCut Hive (or Pocket).

4. Select Start sync.

Here are some common scenarios of deleting users and/or groups, either in the IdP and/or in PaperCut Hive or Pocket:

Identity provider source	Selection in sync configuration User source	Change and outcome
Some users are deleted	All users	If users are deleted in the identity provider source, they will be deleted in PaperCut Hive or Pocket on a destructive sync.
Some teachers are deleted	Teachers	If users are deleted in "Teachers" in the identity provider, on next destructive sync, those same users will be deleted in PaperCut Hive or Pocket.
Teachers; Students	Teachers; Students	If "Teachers" is removed as a sync configuration User source, on next sync, all users only associated with "Teachers" are deleted in PaperCut Hive or Pocket.
All staff; Teachers; Students	All staff; Teachers; Students	If "Teachers" is removed as a sync configuration User source, on next destructive sync, no changes are made to the PaperCut Hive or Pocket user list. This is because members of the "Teachers" group are also members of "All staff". They are still included in a user source.

What happens to blank, changed, or deleted user attributes?

The user attributes you have configured in PaperCut Hive or Pocket are synced during a sync.

• If a user attribute is blank, on sync, any user data in the matching field in PaperCut Hive or Pocket is not changed. No new data is imported.

• If a user attribute is changed in PaperCut Hive or Pocket, any user data linked to that attribute will be imported into the PaperCut Hive or Pocket user profile for users during the next sync.

• If a user attribute is deleted, it will not sync again. No changes are made to existing user data.

What happens to suspended/disabled accounts in my identity provider?

If your sync configuration's connected identity provider User Source includes suspended or disabled accounts, they are synced into PaperCut Hive or Pocket in a suspended state. This means that they can't access MFD functions like printing and copying, and they also can't log in. The ability to exclude suspended users from a sync is coming soon.

Are archived users included during a Google Workplace sync?

No, archived users are not synced from Google Workspace to PaperCut Hive or Pocket.