Volume Purchase Program (VPP)

Apple’s Volume Purchase Plan and License Management

What is VPP?

VPP, or more formally, Apple's Volume Purchase Program, is a mechanism by which an organization or institution can purchase macOS and iOS applications and books in bulk and provide these to their end users. The process revolves around creating a VPP administrator account, creating one or more VPP facilitator accounts, enrolling devices into the MDM (mobile device management) system, and assigning applications and books to the end users. More details on Apple's requirements and capabilities with VPP are available at the following two URLs:

VPP is supported in FileWave for both iOS and macOS. There are two mechanisms for assigning applications and books to clients - redeemable codes and managed distribution licenses. Redeemable codes provide a set of codes to be used for content distribution, but once given out, the content legally belongs to the owner of the Apple ID that redeemed the code. Managed Distribution provides licenses that can be associated and revoked, so the purchasing authority retains ownership of the license (with the exception of books, which always are owned by the person to whose Apple ID the license was distributed to). This allows you to assign institutionally-purchased applications to end users as needed; then revoke the licenses for those apps at a specific time, returning the licenses to your control.

Differences between redeemable codes and managed distribution licenses

The original model for mass deployment of content was using redeemable codes. The VPP administrator purchased applications from the Apple VPP site. Apple provided a set of codes in a spreadsheet that could be downloaded. Those codes were then used to create an application Fileset for installation on managed devices, or were provided to the end user for them to redeem. Once a code has been redeemed, it cannot be reclaimed by the MDM administrator. VPP redeemable codes are available for applications and books. Note: With the current VPP system, free apps and books cannot be obtained with redeemable codes, only managed licenses.
It is also possible to have all of your redeemable codes exchanged for Managed Distribution licenses. This Apple Support article describes the process: https://support.apple.com/en-us/HT202863.
Apple's newer model for application license management allows you to assign licenses to users and revoke those licenses at a future date. This mechanism is called Managed Distribution and it applies to VPP purchases of any free content, applications, and books. When a license is assigned to a user, that user sees the item in their Purchases list, as well as in FileWave's Kiosk. When the application is no longer needed, or the user is no longer associated with that institution, the MDM administrator can revoke or remove the license. FileWave regains that license for distribution to another user.
Note: This process is only valid for applications since Apple requires all book distributions to be permanently assigned to personal Apple IDs.

Managed Distribution - user versus device assignment

Initially, Managed Distribution required association to a unique Apple ID for any deployed content. With the release of iOS 9 and OS X 10.11, VPP managed distribution licenses acquired the ability to be assign applications directly to a device, provided the developer allows it. This method opens up a huge benefit in layered deployment models. Now an institution can assign core applications directly to devices in carts, labs, or even on 1:1 deployments.

How FileWave works with VPP

There are several approaches to using FileWave with VPP. The deployment workflows relate to the overall control of the application(s) to be deployed. The actual workflows discussed are covered in detail later in this Chapter.
Redeemable Codes - A Fileset is created that links to the App Store and provides a redeemable code for each device that is associated with that Fileset. When the user accepts the installation, the code is redeemed against that user's Apple ID. The code, once redeemed, belongs to the end user and cannot be retrieved by the FileWave administrator. If the user refuses the installation, the code is reserved for the next 24 hours against that device, then it is returned to the pool for that Fileset. Note: Under OS X, all application associations must be done as Kiosk items.
Managed Distribution licenses - For the managed distribution method, FileWave doesn't manage users directly; but associates users with specific devices. All of this is done through the linkage of an Apple ID and the FileWave MDM. Whether you use individual Apple IDs, in the case of a BYOD or full 1:1 deployment, or institutional Apple IDs in the case of a managed lab or cart, the application licenses remain under your control.
If you assign the licenses to devices, there is no longer a requirement to match an Apple ID with the device. You can, for example, use a generic LDAP or fixed MDM authentication account to enroll the device(s), then just configure your Filesets to be assigned to the device.
When you assign or associate Apple Store content through a Fileset to a user's Apple ID, the end user will see that content in their Purchases in the App Store.
For iOS devices, you could use Apple Configurator to prepare, and possibly supervise, the device; then turn it over to an end user to add their own content using their personal Apple ID. You could use VPP direct device association to place the applications onto the device, then let the user add items as they see fit. With this model, you, as the FileWave administrator, would be responsible for maintaining the institutional content and software, while the end users would be responsible for any applications and content they install.

Setting up your FileWave server for VPP

In order to provide your users with content from VPP, you need to establish an institutional VPP account and link that account with your FileWave server. If you are an educational institution, you need to follow the steps provided by Apple on setting up VPP for Education: http://www.apple.com/education/it/vpp/. If you are a business or enterprise customer, you need to use the VPP for Business instructions: http://www.apple.com/business/vpp/. Once you have your VPP account, you are ready to configure FileWave for VPP support.
Important - Ensure you do not have another VPP system, such as Apple's Profile Manager or Apple Configurator, active with your VPP token when you set up FileWave for VPP. This will cause problems with your ability to manage VPP user accounts.

Set the VPP token(s)

When you signed up for your VPP account, you were provided a coded token that allows you to configure FileWave for VPP. Use the instructions in Chapter 2 to configure your FileWave Admin Preferences for VPP.

Synchronize data with the VPP server for VPP

Once your token(s) are active, the FileWave Server will automatically synchronize with Apple's VPP service. Depending on how many items you have in your purchase list, this process may take a while. When you have synchronized your VPP data with your FileWave Server, you should see any VPP Managed Distribution purchases listed in the License Management section of FileWave Admin.
The first time after you set up VPP, you can force a full synchronization by holding down the option key, and clicking on the Synchronize button.
You should see entries in the License Management view that match your purchase history.
Note: Only VPP Managed Distribution licenses will be displayed here. The older VPP Redeemable Codes, if you have any, will still be located in the "VPP Code Management" assistant in FileWave Admin. When you purchase redeemable codes, you must download the spreadsheet and import it into FileWave using this assistant.

Adding licensed applications to your FileWave Server

The process of adding content for VPP code redemption or managed distribution is extremely simple. When you purchase any content in the VPP Store, upon a VPP sync with your FileWave server, the items will appear in your License Management pane. First, you make your purchase in the VPP Store:


Once you receive confirmation that the purchase is completed, you can force a sync of VPP in your Preferences, or wait for the overnight sync. In FileWave Admin, go to the License Management pane and click the Refresh button in the toolbar. You will get the following dialog:


That dialog tells you that your purchase information has been loaded into FileWave; but there is no corresponding Fileset. At this point, you should click on Yes and follow up by updating the Model to refresh the database. You will be taken to the Filesets pane, and your new VPP application Fileset will be waiting:


Back at the License Management view, it will display the new license:


At this point, you can begin associating the new content with your enrolled devices.

VPP and iBooks

If you purchase managed distribution licenses, you have control over the assignment of those licenses to end users, regardless of the deployment model. The one exception to this is with books. Free books can only be provided with managed distribution licenses, yet the item becomes permanent property of the assigned user. Books available for a cost do allow the use of redemption codes; but the same rules apply - books cannot be revoked or reassigned. Books must also be assigned to personal Apple IDs; they are not allowed to be assigned to institutional Apple IDs per Apple's legal guidelines, nor can they be assigned to devices.

Manually creating Filesets from VPP managed distribution content

By default, your VPP managed distribution license purchases should automatically show up in License Management, and upon a Refresh of the pane, you should get a dialog asking you to create a Fileset for your purchases. If, however, you have items that are displayed in the License Management pane, and they do not have a corresponding Fileset, you can manually correct that problem.

Create a mobile Fileset for a managed content item

All VPP purchases now appear in License Management as soon as the FileWave server syncs with the Apple VPP site. The first time you access this area after setting up your FileWave Server, you will get a dialog box telling you that a Fileset can be created for each of the licenses. You can also right-click on any purchase and create a Fileset.

Redeemable codes

For redeemable codes, you will need to download the code spreadsheets. Log into your VPP account online, and select your Purchase History. For any content that you purchased using redeemable codes, you will see that you are able to download the codes in the form of an .xls spreadsheet. Note: This spreadsheet will always be kept up to date on the VPP site. As you, or your users, redeem codes, the online spreadsheet will be updated to show remaining codes.


Once you have downloaded the spreadsheet(s) as needed, you will need to go to Assistants / VPP Code Management. This pane is used only for linking redeemable codes to Filesets. You have two methods for bringing codes into FileWave Admin, by importing the spreadsheet or manually entering the code information.


The Import Spreadsheet… method is quite simple. Select the Fileset (if there are multiple Filesets for a purchased item, just pick one), then click on the Import Spreadsheet… button, locate your downloaded VPP .xls file, and import it. The dialog box tells you to verify that the codes you are uploading into FileWave Admin match the item you want to link them too. You will get errors if you try to match codes to the wrong content, or try to import an older spreadsheet into the set once you have begun redeeming codes. Once you have imported codes, you will see them listed next to your selected Fileset.


The Import Manually… button lets you import a custom text file you create. The format is the URL as you would see it on the App Store or on the VPP spreadsheet, or just the redeemable codes. For example, the file custom_codes.txt could look like this: https://buy.itunes.apple.com/WebObjects/MZFinance.woa/wa/freeProductCodeWizard?code=Y6XJ69TFXDEJ
Y4XJ69HYTFEB
A benefit of using FileWave for working with redeemable codes is that you don't need to breakdown your spreadsheets into separate sections to match the different sets of the same content you plan to deploy. You can just select the number of codes you want to assign to specific Fileset and drag those codes onto that Fileset. This example shows dragging one code from the main Fileset for Digits onto the Fileset meant for the testing team.

Managed Distribution Licenses

The managed distribution content licenses are treated as part of a pool. When you look at each Fileset's details, you can see the status of your licenses:


You will be required to track the usage of your licenses to avoid exceeding your allowed limit. If you distribute more copies of an item than you have licenses for, you will get installation errors.

VPP Managed Distribution User Management

The most complex portion of the VPP Managed Distribution system is the interaction of the end user and the VPP license architecture. The process is as follows:

Note: Never use your VPP account Apple ID for personal purchases.

Creating users for your devices

Apple's VPP manages licenses that are either assigned to a device, or assigned to specific user's Apple ID. In the Assistants / VPP User Management pane, you can see all of your enrolled devices, and a list of VPP users.


In the upper left is the list of enrolled devices. In the upper right is the list of VPP users you need to create. The lower portion of the window displays the device and users who are associated with each other for management purposes.
Note - You do not need to do this process manually for a population of several thousand users. FileWave provides the ability for you to link your LDAP directory and your enrolled devices together automatically.


The option exists to have a VPP user created automatically as each device enrolls. When doing batch rollouts of iOS devices, this may be your best option.
Note: If you use only VPP device assignment, and do not assign licenses to any unique users, you will not need to work with the VPP User Management pane. FileWave assigns a "ghost" VPP user account to each device to handle device assignments. You cannot see these accounts and will not need to manage them.
In the VPP User Management pane, we can manually assign a new VPP user for each device. This will give us a VPP user account with blank fields:


The VPP Client User ID is a construct that is used by FileWave to facilitate the association of a device - which FileWave can manage - to an Apple ID - which belongs to a user. The account is unique, and has one of three states: registered; associated; or, retired. Registered means that the account is assigned to your FileWave MDM by Apple. Associated means that the account is linked to an Apple ID through an iTunes ID hash and the user can have licenses assigned to them. Retired means that all licenses assigned to that VPP Client User ID are revoked and can be used again.
An Apple ID can be associated with multiple VPP Client User ID's; but only one VPP Client User ID can be associated with an enrolled device. It also allows users with multiple iOS/macOS devices to have a single VPP Client User ID associated with those devices.
If you link your LDAP accounts to FileWave, then the directory service will have the users associated with a VPP account. This will fill in those blanks, and make the next step easier. LDAP authentication is covered in Chapter 3.

Inviting users to the FileWave MDM VPP

Apple requires the end user to actively link their Apple ID to your FileWave MDM. You must send an email to each VPP user account after you have provided their email address. Click in the Email Address field for the VPP user account and enter a valid email address. The does not need to be a user's Apple ID email address, just an address where the user can get a VPP MDM request.


Once you have entered a valid email address, the button to send an invite to the user will be active.


The user will get an email asking them to activate the link to their "VPP organization;" i.e., your FileWave MDM server. This email account does not need to be the email that person uses for their Apple ID. It can be an internal email address used within your organization/institution, or any common email address the user may provide.


Once the user clicks on the link to the iTunes Store, authenticates with his or her Apple ID, and gives permission, the user will get notified that he/she can now be provided with content from your FileWave MDM.

FileWave and macOS VPP users

The process for macOS computers and users is almost identical to that of iOS users. When you add an macOS computer as a FileWave Client, it will show up in the Manage VPP Users… window.
Note: Direct device assignment is still an "in-progress" thing with OS X. Full functionality from Apple will be available in a future release.
You still have to go through the user assignment process unless you automated that in the VPP preferences. The user email will have to be entered unless the user logged into the device with an LDAP account and that account had a valid email account attached. If so, you can have the FileWave server automatically send off an invitation to associate that user with the FileWave VPP. Whichever process you use, the end user will still have to agree to associate with your system. Once that is done, you will be able to assign applications and books to that user through Filesets linked to the VPP managed distribution system. Here's the final view of the Kiosk and the App Store after some Filesets are associated with the client.

Retirement

Note: If you retire a VPP user account, it cannot be used again. We suggest that you DO NOT test "retiring" VPP user accounts on actively enrolled users.

Where OS X VPP differs

One key difference between iOS and macOS VPP managed distribution is in the way the applications are installed. You will be asked on the client if you want to turn on automatic application installs; but it refers to apps downloaded onto other devices. What that means is if the end user has a single device, they will get apps showing up in their App Store / Purchases section and those apps will not automatically install on the device. The user must do the installation manually.
This also affects Kiosk operations. If an application is in the Kiosk, just selecting it and telling it to install may not result in it showing up in the user's Applications folder - until they go to the App Store / Purchases list and install it from there.

Revoking licenses using FileWave MDM with VPP managed distribution

When a user is no longer part of an institution, or is no longer working on a project or class that requires a costly application that you have a limited number of licenses for, you can revoke the managed distribution license for that application and return it to FileWave's inventory.
The process is the same as you may have already used to remove any other assigned item to a managed device with FileWave - you merely dis-associate the Fileset. Once the model has been updated, you will see the application licenses returned to your license management pool. The behavior of the application on the client device is dependent on the way the application developer designed the revocation settings into the app. A developer can set the app to continue to exist for up to 30 days on a user's device. This also means that the application will remain in the user's purchased list in iTunes.
Note: macOS X computers may take several minutes before noticing the applications are no longer assigned to them. In some cases, if the user has both an iOS and macOS device associated with your VPP system, you may see notifications pop up on the iOS device before the macOS computer gets the word.


VPP Token Renewal

Description

VPP Tokens need to be renewed once a year. FileWave dashboard will alert when any VPP Token is about to expire by changing to yellow and stating duration until expiry; subsequently turning red once a VPP token expires. Use the steps below to renew VPP Tokens. 

Requirements 

The ID accessing School or Business should require the appropriate permissions to access the below mentioned VPP token.  This will likely be Content Managers or higher, e.g. Administrators.  Apple recommend Administrators do this where the management account has multiple VPP accounts, split across an organisation, such that all may be renewed in unison.

Directions

Steps:

  1. Navigate to the appropriate Apple account, e.g ASM:



  2. In the ABM or ASM portal - navigate to the account name at the lower left side, select "Preferences," then "Payments and Billing" (apps and books is usually the default tab), Then navigate to "Content Tokens". "Content Tokens" will contain the VPP token download option for each location. Select the appropriate token to Download as highlighted:

    image.png



  3. Log into the FileWave Admin console specifically as fwadmin, and from Preferences > VPP & DEP select "Configure tokens" and enter the 'fwadmin' password:



  4. From the "Edit VPP service tokens" window double-clicking the appropriate token will open the "VPP server token" showing current VPP token details:


  5. Use the 'Import' feature to select the downloaded token from Step 3. Email is not required, but may be a good idea where multiple tokens are configured:

  6. Note: You may also see this pop-up, but this is just a warning to let you know how many Filesets a token is associated with. This is not an error, please click yes to continue.



  7. On saving, a prompt will appear indicating it may take a while for synchronization.  This window will automatically close at completion. 


  8. During any synchronization, an additional prompt may appear if there are new VPP App licenses that do not yet have Filesets.  Allow creation if desired.

Congratulations, the VPP token is now configured for another year!

VPP App Updates for macOS / iOS / tvOS devices

Description

As standard, VPP Apps on devices should update automatically, regardless of how they were installed, e.g. Kiosk or Standard Deployment.  They may also be occasion to block VPP Updates, without locking the entire device.

Information

By default, with no defined customisation, FileWave will trigger automatic updates of VPP Apps installed on devices.  

At certain times, FileWave Server requests the list of installed applications.  MDM commands to devices may be observed in the 'Command History' tab of a device's information:

image.png

At minimum, this will occur every Automatic Verify (usually 24hrs), assuming devices are online, but other actions should also trigger these events.  For example:

If an installed App has an update, that App will be flagged.

Where an App has an update Flag, a new command to instal the application is queued with the device.  This should be true for all Apps that have an update, one entry per App.  On receipt of the request, the device communicates with the App Store and acknowledges the request to update back to the FileWave Server.

image.png

FileWave does not specify the version when a device honours a request to update an App, it will update to the latest, compatible version currently on the App Store.

Included in FileWave Anywhere, is the option to determine timings of when VPP App upgrades may take place.  Please view the following KB on this topic:

https://kb.filewave.com/books/apple-school-business-manager/page/vpp-application-upgrade-timing

Managing Updates

There have been instances where disabling auto updates of VPP Apps has been required; due to unexpected behaviour from the App Store.  In such cases, it can be desirable to either block updates completely or block updates per App.

Beyond the above mentioned method to manage VPP App upgrade timings, it may be desirable to block certain versions of an App.  FileWave has some additional options for VPP App management.

Overriding this behaviour may be done by adding options within the custom settings:

# macOS/Linux

/usr/local/filewave/django/filewave/settings_custom.py

Options available are:

Key

Description

SELF_HEAL_APPS_BY_VERSION

Enables/disables all VPP App updates

IGNORE_PREINSTALLED_APPS_SELF_HEAL

Block all update attempts for a defined App by Bundle ID (Unmanaged Apps only)

IGNORE_ITUNES_VERSION

Block updates, not only by a defined App Bundle ID, but only blocks defined version numbers

Directions

Each example below involves editing: settings_custom.py.  Any changes require apache to be restarted.  Where the App Bundle ID or version is required, this may be observed in a device's Installed App list.

SELF_HEAL_APPS_BY_VERSION

Add the following line will block all updates of all Apps:

SELF_HEAL_APPS_BY_VERSION = False

To revert this behaviour, either set this as True or remove the entire line.

IGNORE_PREINSTALLED_APPS_SELF_HEAL

This option will only prevent erroneous attempts to update unmanaged Apps, where the device reports an incorrect Bundle ID.  As an unmanaged App, it may not be updated by MDM anyway, but installation errors would be seen in the Command History.

Obtain the Bundle ID of the App, then add the following option. For example, to block iMovie, Pages and Keynote:

settings.IGNORE_PREINSTALLED_APPS_SELF_HEAL = ("com.apple.iMovie", "com.apple.Pages", "com.apple.Keynote")

This is a comma separated list. Add each Bundle ID per App to be blocked for updates.

To revert this behaviour, either remove the Bundle ID no longer required for blocking or remove the entire line.

IGNORE_ITUNES_VERSION

Obtain the Bundle ID and version of the App to be blocked. The settings are set out as:

'Bundle ID': [(version to block, version currently installed)]'Bundle ID': [(version to block, version currently installed)]

'Bundle ID': [(version to block, version currently installed)]

The below example will:

settings.IGNORE_ITUNES_VERSION = {
'com.apple.keynotes': [('3.0', '2.7'),],
'com.apple.iMovie': [('10.1.14', '10.1.13'),],
'com.apple.Pages': [('8.2', '8.2'),],
}

The Pages example prevents an App from continually attempting to update, where the version on the iTunes Store matches that on the device, yet the device is still reporting an update is required. Add or remove entries per item to be blocked.

Taking this one step forward, consider the above Keynote example.  Device has 2.7 installed, but version 3.0 is set to be ignored.  If version 3.1 were to be released, the device would upgrade to this version, if it were the next latest version available on the App Store, after receiving a new InstallApplication command.

To revert the behaviour, either remove the Bundle ID and versions no longer required for blocking or remove this entire code entry.

White Space
Note, there should be no 'white space' before the added key: spaces, tabs, etc. Doing so will result in the server becoming non-responsive.

Apache should then be restarted:

# macOS/Linux

/usr/local/filewave/apache/bin/apachectl graceful

Redeeming VPP/Gift Codes

Description

For those that can't use VPP, Redeemable Codes provide a way to assign Licenses to iTunes Store IDs , in order to deploy Apps to devices.

Who has used the licence, and how manageable are they ? This article gives an overview over how to find out, manage, and troubleshoot this process.

Information

After the codes have been added into the FileWave VPP Codes assistant ( available from Assistants - "Manage VPP Codes" ), you should see:

Automatic Assignment

Any licences available here may be redeemed automatically by the user of the device, with the following process:

  1. Associate the Fileset
  2. Update Model
  3. When device checks in, the user will be prompted to accept the installation with their Apple ID
  4. If the user accepts the installation, this code will no longer be available for use and the App will belong to that Apple ID
  5. The code used, will automatically disappear from the found VPP Codes from the uploaded file
  6. Instead, the code will now show in the redeemed list and will show which device was used when the code was redeemed

Unfortunately, Apple do not allow visibility of which user accepted the licence.

Have code been used?
In rare circumstances a device may show a code as 'Redeemed Automatically", but the code was not actually redeemed and could be re-assigned. If you suspect this to be the case, the codes in question can be re-imported from a CSV. For efficiency, we recommend only re-importing suspected unused codes where possible. For VPP codes, downloading the file again from Apple will provide a new file with just the unredeemed codes. Gift codes though cannot be re-downloaded in this way.

A clue could be if a device shows more than once with differing codes. You could try re-adding the first code that had been redeemed via this device by date, from a new CSV import. If a code re-imported form CSV has indeed been redeemed, next redemption attempt for this code will fail, the code will be removed from the list and an attempt will be made with the next code in the list.

You may experience this when several users use the same device or if the code was automatically associated, but redemption by the user was not finalised.

Manual Assignment

You may also choose to allow the user to manually install the application.  In this case, you would:

Any codes configured to be manually redeemed, that have not been redeemed, may be pulled back to the pool of licences (unredeemed) such that they could be automatically associated instead.

Warning
If a code has been provided to a previous user, e.g. by email, that was not redeemed and you 'Unredeem' the currently unused code, this code could still be used by the original user as they have the code details. The first Apple ID to use the code will own that App and that code will no longer be useable.

VPP Application Upgrade Timing

What

As a FileWave administrator, I want more control over when VPP applications receive updates so that they happen after work or school hours.  In the past, this was not possible.

When/Why

You can now pick Never, Always or Scheduled for VPP application update settings in FileWave 14.6+

How

As shown in the below image you can go in the Web Admin to Sources and then change the VPP update settings to either Never, Scheduled, or Always. If you pick Scheduled then you will have the option of Weekend, Non-Business Hours, or Non-Business Hours and Weekend. The days and times shown are from the client's time zone. 

VPP User Assignment for iBooks with Managed Apple IDs

Description 

Managed Apple IDs and Licenses

Guide will go over setting up VPP User assignment for deployment of iBooks with Managed Apple IDs. This guide will also implement new functionality starting in FileWave 12.7 for silent invites for VPP. If you are not using Managed Apple IDs you will need to use the steps on Apple’s Volume Purchase Plan (VPP) and License Management under "VPP Managed Distribution User Management".

Silent invite

While most of the apps now support Device Based assignment, a few apps still require user based licenses. All iBooks for instance require VPP User assignment and can not be assigned based on Device. Managed Apple IDs can be associated to VPP User assignment apps and have to be associated to a VPP user for the corresponding VPP token so the token organization can assign licenses to the Apple ID.

To ease Managed Apple IDs and VPP user management, Apple introduced a change in VPP to automatically, silently link a VPP user and a Managed Apple ID.  This makes organization life easier as they don't have to rely on human interaction to link their Apple ID and all possible organizations using the Apple App store on each device. 

With a VPP user associated to the user's Managed Apple ID - and therefore user based licenses, including those for books, can be deployed, without the need of manually joining the organization.

When working on this everything must be related to the same organization - i.e. you can only assign a Managed Apple ID from "Organization A" to an ASM VPP Account from "Organization A".
A Managed Apple ID can't be associated to a VPP user from a Legacy token for instance, or from another organization.

Steps 

1. Assign a user in the Classroom tab to the student device. This will need to be the user that is assigned to the Managed Apple ID that will be logged into the iOS device. 

VPPinvite.gif

2. Sign in on the device with the  Managed Apple ID that is assigned to the user associated in step 1.
3. Create a VPP User for the device for the VPP token you want to assign iBooks or User VPP apps to. This window is found in the FileWave Admin under "Assistants" → "VPP User Management".

This token must be an ASM account token.


VPPinvite2.gif 

4. Associate the VPP Fileset for the iBook or VPP Application to the iOS device. 

The Application must be purchased from the same ASM VPP Token that you assigned the device to in step 3

5. Update the model
6. You are done and the Apple ID on the device will automatically be associated to the VPP License you are deploying without input from the user. 

Unremovable VPP Applications

What

There is a new options for VPP apps, namely preventing the user from removing them.  (iOS/iPadOS 14+ required)

When/Why

We may want to prevent users from removing a VPP licensed and MDM delivered application if it is essential for their day to day use.  Previously a user could remove any deployed application (although it would be reinstalled by FileWave on the next verify).

How

There is nothing special you must do to enable this attribute.  By default, deletion is disabled and you should see the below in each of your VPP filesets.

Note the language of this dialog...not checked means the app is NOT removable.  Checked means the user can remove the app in question.

What we should discuss though is how this setting behaves, so that it is understood:

  1. This setting is NOT retroactive...that is, if you have already deployed an app, like iTunes Remote shown above,  the user of that device can still remove it
  2. But, if a new device is enrolled and receives this payload, they will not be able to remove it
  3. Or, if someone who had it does remove it, and FileWave re-pushes it (on verify), then the newly installed app will NOT be removable
  4. This checkbox behavior does NOT affect Kiosk based app distribution, regardless of checkbox setting
    1. Any App installed by the user through the Kiosk can be removed by them as well (this setting is basically ignored)
  5. The checkbox does default to unchecked, so if you do have something deployed as a push, but you want folks to be able to uninstall, then you should modify that fileset accordingly

VPP Notifications (Apple VPP API v2)

What

Starting from FileWave version 14.6.0 we added support for a new Apple API for App and Book Management within the Apple Volume Purchase Program. With FileWave 15.1.0 this API became the default. The main difference compared to the previous version is that the new API is asynchronous. When we send a request to create / update / retire users or associate / disassociate assets we get a unique event identifier in response, which we use in the scheduler task to retrieve the status of an asynchronous event. There are no visual changes in your environment, except that the new API is more reliable, and expandable.

When/Why

In short, the new VPP 2.0 protocol is better, but out of an abundance of caution, it was not enabled by default on FileWave version 14.6.0 through 15.0.1 but with FileWave 15.1.0 it will become the default.  

How

The new implementation was not yet turned on by default, until FileWave 15.1.0. To turn it on for prior releases you need to add a line to your /usr/local/filewave/django/filewave/settings_custom.py and after that restart server.

If you are a hosted customer you will have it enabled since your server was upgraded to 15.1.0 or beyond.

VPP_V2 = True

For troubleshooting it can be set to VPP_V2 = False to go back to the VPP v1 API. 

The next step must be done for every server no matter if you are hosted or not.

In FileWave Central to go to Preferences → VPP & DEP and if the Enable VPP Notifications item can be enabled then VPP 2.0 is active (14.7+ only). It will be greyed out otherwise, and the checkbox will not be selectable. You should check the box to Enable VPP Notifications as shown below.

Once you Enable VPP Notifications, you should click Synchronize on the same preference screen and if it is successful then VPP v2 Notifications are working. If you get an error 9720: The provided notification URL is not reachable, then Apple is unable to connect to your server.  Apple must be able to reach your FileWave server directly from their 17.0.0.0/8 network. 

Screenshot 2023-12-11 at 17.01.23.png

Digging Deeper

Logging

If you enable it or are running a version of FileWave of 15.1.0 or newer, you can check filewave_django.log. Lines with 'Sync VPP v2' is the confirmation that the new API is activated.

Email Address

One important change in the new API is that when we create a user we need to specify an email address. For BYOD devices we are using Managed Apple ID, for DEP devices - Device Assigner Email (it is not available when option 'Create VPP users for newly enrolled devices' is checked), if before mentioned is not available, we use Organization Email Address, and as last resort - 'email.not.set@<your_mdm_host>'.

Reachable by Apple

By default, FileWave uses the following endpoint:

This endpoint needs to be reachable and valid from Apple services.
You need to make sure that the TSL certificate is trusted by Apple and that Apple services are not blocked by any networking rule.

Server Port refers to the port configured in Mobile Preferences, which is likely either 20445 or 20443:

https://{server_host}:{server_port}/api/vppv2/notification

If the FileWave Server is not accessible by Apple on the defined port, disable VPP Notifications, otherwise VPP will fail to work correctly.

If for security reasons or due to your network configuration, your FileWave server can't be reached by Apple services directly, it is possible to define a different URL that will be used by Apple. This can be done by editing the /usr/local/filewave/django/filewave/settings_custom.py file adding the below line and then restarting the server. For hosted customers, you will need support to set this for you.

settings.VPP_NOTIFICATIONS_CUSTOM_URL = "https://server:port/url"

Then you need to make sure requests to this endpoint are forwarded to your FileWave instance.

Migration to VPP Location Based Tokens

With Apple School Manager you can:

To take advantage of these new features in Apple School Manager (ASM), you will first need to transition your institution from the legacy VPP token system to ASM. Below are some key steps to follow to help you understand and plan to ensure a successful transition.

You must read and follow the steps below to ensure a successful migration to VPP Location-based tokens! If you’re unclear about any of the steps please contact your Apple, or FileWave, representative before proceeding. Not following the steps below can lead to:

Unable to deploy apps due to lack of licenses
Apps being removed
Loss of app data

Migration

If you have codes still

How do I know if I have code?

To see if you have any codes in your account before migration, log in and go to “View Purchase History”
If any previous purchases have “Download Codes” in the last column you will need to request those be migrated to managed distribution.

How do I migrate codes to Managed Distribution?

  1. Visit https://www.apple.com/support/itunes/vpp/ and for “What do you need help with?” select “Other”
  2. Use the same institution name (and ideally the same email) as it shows in your Account Summary section
  3. Describe your issue and a representative should be in touch.

Invite VPP Purchasers

If you have purchasers with existing VPP accounts that aren't in Apple School Manager or in Apple Business Manager, invite them to join your organization before you migrate to Apps and Books.

One Purchaser per location

For the best migration experience, migrate only one purchaser per unique location. You can do this in one of the following ways:

If each purchaser migrates to a unique location, all licenses — assigned and unassigned — will move to Apps and Books.

Initial migration

All licenses that move during migration will be associated with the new location token to which they move. Any assigned licenses that don't move during migration remain associated with the purchaser's legacy token. All tokens that have associated licenses must be uploaded in MDM.

Location-­based tokens

Apps and Books use location ­based tokens. All licenses purchased for or transferred to a location associated with that location's token.* Legacy tokens from the VPP portal are account-based tokens. Purchasers can access tokens for all of their locations in the Apps and Books section of Apple School Manager's Settings or Apple Business Manager's Settings. Only one person needs to upload location tokens to MDM. Legacy tokens aren't needed after all licenses are moved to a location.

When you create a location, the location is in an "untouched" state, which allows Apple to transfer all licenses, including licenses currently in use, from a legacy token. As soon as anything is done on this location (buy apps, transfer token, change permission...), the location is not "untouched", therefore only unused licenses are transferred. So it's critical to NOT do anything with a location before migration happens.

Migrate all VPP purchasers

When you're ready to migrate to Apps and Books in Apple School Manager or Apple Business Manager, all purchasers should migrate at the same time. Each purchaser must migrate their account. Migrate by clicking Get Started in the Apps and Books section of Apple School Manager or Apple Business Manager, then selecting the appropriate migration location.

After all purchasers migrate, you can take full advantage of the new features.
If your organization decides not to use Apps and Books, VPP purchasers can continue to use the legacy VPP portal at vpp.itunes.apple.com until December 1, 2019.

Assigned book licenses can't be moved and remain assigned to a user.

If assigned licenses don't transfer

Only unassigned licenses will move to a location if any of the following scenarios occur:

If assigned licenses don't transfer, they remain associated with the purchaser's legacy tokens which should remain uploaded to MDM with the location token. After you unassign an app from the legacy token, you can transfer the licenses to a location in Settings > Apps and Books in Apple School Manager or Apple Business Manager.

Updating Token in FileWave Admin Preferences

Once you have successfully migrated to the location-based tokens, you’re ready to update the legacy token(s) in FileWave! You will need to download your new location-based VPP token(s) and follow the directions below to update your VPP token in the FileWave Preferences.

Downloading New Token(s):

  1. Log into your ASM/ABM instance
  2. Click "Settings" on the lower left
  3. Click "Apps and Books" in the center column
  4. Scroll down on the right to find the Locations Table
  5. Click "Download" next to each location needing to be updated in FileWave 

Updating in FileWave:

  1. Connect with FileWave Admin and open the preferences
  2. Click on the VPP & DEP tab
  3. Click on "Configure tokens"
  4. Double-click on the VPP token you need to update
  5. Click the "Import" button and select your new location-based VPP token

VPP Token Revoked Error

Problem

"VPP token is Revoked" error is displayed in the FileWave Admin> Dashboard or when trying to run a manual VPP sync in the "VPP and DEP" tab of FileWave Admin preferences. This can be caused if you try to enter the same VPP token in Apple Configurator. 

Solution

The solution for this error is to renew your VPP token in FileWave. For renewing your VPP token we offer the below Knowledge Base article for this process. Renew Your VPP Token

VPP Kiosk Error Details

When you associate VPP assets via users association there can be messages in the kiosk. Here is what these messages can mean:

unavailable for this application's organization

When the total available count of license is 0. Meaning you have no purchased licensed for this Application

unavailable for this application

When the available count of licenses is 0. Meaning you have run out of licenses for this VPP item.

application is not device assignable

The Developer of this application has not allow their application to be assigned to devices

acquired (but your VPP account was retired)

As stated, your invitation to the organizations VPP program has been retired

available

All is well

available (but your VPP account is not)

The application is assigned as User in Admin, but there is no VPP user account tied to the device

acquired

Device has a license for this vpp item

VPP Device Assignment

About Device Assignment

With the release of FileWave version 10 and iOS 9 comes a new, simpler way to assign licenses for apps purchased through Apple's Volume Purchase Program (VPP). Unlike VPP's previous options, which employed codes or user assignments, you no longer need CSV uploads or registered Apple IDs on the devices. The new process for VPP allows users to send out and pull back licenses to Apple devices regardless of whether an Apple ID is present.

The steps below walk you through the VPP device-assignment process of app deployment. Before completing the guide, make sure the following requirements are met.

Requirements

iOS 9+ (FileWave version 10.0+)
OS X 10.11.1+ (FileWave version 10.1+)
OS X Devices MDM Enrolled (DEP or Profile Enrollment)
VPP Token in FileWave (Section 3.12 in the FW manual)
Device Assignable Apps (see the "Purchase Apps" section below)

Restrictions

All apps in the VPP Store are opt-in only for device assignment. This means not all apps can be assigned to devices, so check compatibility before purchase (see the "Purchase Apps" section later in this document for details). User assignment, not device assignment, must be used for books purchased through VPP, requiring every Apple device to have a separate Apple ID. Alternatively, PDFs, ePubs, or iBooks can be deployed to iOS 8 or above devices directly with the "Document (iOS 8+)" Fileset option under New Model Filesets.

Steps

Prepare FileWave

Go to the VPP & DEP tab in the FileWave Admin Preferences and click on the "Configure tokens" button. Then sign in with your superuser credentials (by default, this is "fwadmin / filewave").

On the bottom of the new "Edit VPP service tokens" window, you'll find the "Create VPP users for newly enrolled device" pane. Be sure the box is unchecked and then close the window. Note: With this option unchecked, if you still want to employ user assignment for VPP books, non-device-assignable apps, and devices not on iOS 9 or OS X 10.11.1 or above, you'll need to create these VPP users manually in the VPP User Management window under the Assistants menu.


createVPPusers

Back in the FileWave Admin Preferences window under VPP & DEP, you'll see a line that reads "Preferred license distribution model to use for new associations." Use the drop-down menu to select Assign to Device. This makes device assignment the default for any new VPP Fileset associations. Then click OK at the bottom right to save and close the preferences.

PreferredAssociation

Purchase Apps

To purchase the apps, go to the following URL: Apple School or Apple Business. There you'll be asked to choose Education or Business and sign into your VPP account.

Use the search field on the top left to locate the app you want to purchase licenses for. After you select the app, you'll be directed to the Purchase and App Details screen. From there, you'll determine whether the app is device-assignable.

The Compatibility section of the app details should read "Device-Assignable." If it doesn't, user assignment needs to be used (requiring an Apple ID for each device).

compatibility

After confirming that an app is device-assignable, you can complete the purchase. Put the quantity of licenses in the Purchase Details section at the top, click Review Order, and click Place Order.

Note: Make sure you purchase enough licenses. If you associated the app with 100 devices but you've purchased only 50 licenses, only 50 devices will be able to download the app. This goes for kiosk associations as well. Associate apps only to devices less than or equal to the number of licenses purchased and reserved.

Import Apps into FileWave and Deploy Them

After purchasing the licenses, you'll get a confirmation email from Apple noting that the licenses are ready. You can wait for VPP to sync with FileWave automatically, or you can expedite the process by forcing a sync in the VPP & DEP section in the FileWave preferences: Do this by clicking Synchronize.

Proceed to the License Management section of FileWave in order to locate new licenses. Click the Refresh button at the top. A prompt will pop up, reading, "FileWave has detected unused VPP licenses. Would you like to create X new Fileset(s) for these licenses now? Note that you will have to do a Model Update to be able to use them in associations." If you click Yes, FileWave will auto-create the Filesets and place them in the Filesets section of FileWave. If you click No, you can manually select the new licenses from the list and click Create Fileset at the top.

CreateVPPfilesetsauto

To double-check how many licenses have been reserved, double-click on the Fileset and look at the Volume Purchase Program - Licenses pane at the bottom. The number of reserved licenses displayed shows how many associated devices can download the app. (Note: If devices have redeemed a license for this app in FileWave, you cannot change the associated token until the licenses are retrieved by disassociating the app form the device.)

appLicense

Continue the process by associating the app with the device, or group of devices, in the Associations tab. In the bottom pane where the associations are located, you'll notice an extra column called License Assignment. New associations will automatically be assign-to-device associations. If you already created assign-to-user associations, these can easily be converted if the app is device-assignable. To convert simply, double-click the association, navigate to the License Distribution tab, and click the Assign License to Device radio button, and the license will change after the device syncs. If the app is not device-assignable, the second radio button will be grayed out. Note that the app does not have to reinstall when the license is changed from user to device.


AssociationLicenseDistribution

Now update the model to save/propagate all changes, and wait the minimum delay between license assignment and install application. The app will automatically install on your device. Note: The default delay is 3 minutes, but you can change it in the VPP & DEP section in the FileWave preferences.

MinimumDelay

Device Assignable Query Check

To make a query to monitor which Filesets are currently in FileWave as device assignable, follow these simple steps.

Criteria:
VPP Asset / Device assignable flag - does not equal - true


QueryCriteria

Fields:
VPP Asset / Product Name


QueryFields

VPP Licensing Reservations (v14+)

The History

Prior to version 14 of FileWave, license reservations for VPP applications could be problematic when purchasing additional licenses.  If you look below, we purchased 25 licenses of this app initially, and the fileset (payload) that was then auto-created had a reservation for exactly 25 licenses.

The inefficiency of this model would show itself whenever we purchased more licenses for this app.  For instance, assume that we purchased 10 additional licenses...the fileset shown above would not change from the original 25, so we could effectively run out of licenses, even though we had 10 more available.  This necessitated a manual change to the original fileset, which was not efficient.

The Change

Starting with v14 reservation of licenses for VPP Filesets (payloads) has made optional in order to offer more convenience when purchasing additional licenses.  You can think of the licenses now more as a dynamic quota than as a restriction.  Here is how it works:

Examples

If you purchased 100 licenses for a new app (Firefox):

Some more complex examples, building on the above: