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 became the default.  

How

FileWave 15.1.0 and later: VPP API v2 is enabled by default; the historical configuration line below is not a setup step for these releases. API v2 and VPP Notifications are separate: notifications can be off while FileWave continues using API v2.

Historical FileWave 14.6.0 through 15.0.1 only: Enabling API v2 required adding the following line to /usr/local/filewave/django/filewave/settings_custom.py and restarting the Server. Retain this information for older configurations, not as a current installation procedure.

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

FileWave 16.4 and later: Apple’s legacy VPP v1 API is no longer available in FileWave. Do not set VPP_V2 = False on a 16.4+ Server. Troubleshoot the current Apps and Books/VPP service by checking filewave_django.log, notification reachability, token synchronization, and the configured delay-based behavior.

Historical releases before 16.4: Some older Servers allowed VPP_V2 = False as a temporary troubleshooting fallback to the legacy API. That fallback ended with FileWave 16.4 and should not be carried into a current configuration.

Starting in FileWave 16.3.x, VPP Notifications no longer use a manual checkbox. FileWave now checks whether Apple can reach the notification URL and automatically turns notifications on or off.

In FileWave Central 16.4.0 and later, open Preferences > VPP & ADE > Configuration, then select Show Advanced Settings under Apps and Books to view the notification state and minimum delay. See VPP and ADE Preferences for the current screenshots and token setup. FileWave 16.3.x shows these values in the single-pane layout illustrated below. When notifications are on, FileWave can act as soon as Apple confirms the license. When notifications are off, FileWave uses the configured Minimum delay (in minutes) between license assignment and Install Application.

Pre-16.3 behavior: older FileWave releases exposed an Enable VPP Notifications checkbox. In FileWave 16.3.x that checkbox is gone, and FileWave decides automatically whether notification-based behavior should be used.

Digging Deeper

Logging

On FileWave 15.1.0 and newer, you can check filewave_django.log. Lines with "Sync VPP v2" confirm the VPP v2 workflow is active. On FileWave 16.3.x, the same logging can help confirm whether VPP notification-based behavior was automatically enabled.

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 TLS 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, FileWave 16.3.x will keep VPP Notifications turned off and fall back to delay-based behavior. On older releases, this was the situation where administrators would leave the checkbox disabled.

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.