How to Migrate to Loyalty v2

The Notificare Loyalty feature is a great way to create and distribute passes to both Apple Wallet and Google Wallet. Users of the previous version will probably want to convert their existing passes to benefit from these new multi-platform features.

However, because there are several major changes compared to the old Loyalty feature, migrating existing passes to the new format can not be done automatically.

One of the key differences is the separation between design and data. In the new version, a Pass Template defines any number of fields that can then be mapped to various placeholders in the designs for both platforms.

It is not safe to assume that the naming of those fields corresponds to the keys of the Apple Wallet fields as used in v1 passes, although in a lot of cases, there will be a pretty straight-forward mapping between those field names. The easiest way to achieve this is by exporting your existing passes, use your new template field names to map the exported data to CSV column names, and import them. The Pass Import type now has a migrate option specifically for this purpose.

Step 1: Create a Temporary Application

To stay on the safe side, we first run a test in a (temporary) test application to see if the mapping produces the correct results. For that, create a new app and set up the Loyalty Service in Settings.

These steps are out the scope of this blog post, but you can follow the instructions in our documentation on how to set up Google Wallet and Apple Wallet.

Step 2: Create a Pass Template

Let's assume that in our existing loyalty setup, we used a template with the following Primary Field:

To be able to migrate to the new version, we need to create a new template (in the temporary application) with a field to hold that value:

We can then map it to the Design of Apple Wallet as a Primary Field:

And use it as the Card Number in the Google Wallet design.

We're now all set up to do a test! It is probably a good idea to manually create a new v2 pass in the Dashboard (again, in the temporary application) to see if it looks correct in both platforms.

Step 3: Export existing passes

If everything is good to go, let's go get some existing data:

This export will give us a CSV that looks like this:

pass_serial,pass_barcode,pass_description,pass_barcode_alt_text,pass_relevant_date,pass_expiration_date,pass_card_number,pass_card_number_change_message
d6e86fc8-2010-42cf-9045-f3dad5e53155,Test-12345-67890,Test Card,1,,,1234567890,

Step 4: Map Column Names

In the pass template we've created in step 2, we've defined a field called cardNumber. From the export, we will need to map the pass_card_number column to pass_cardNumber in the import for the migration. The pass import will check for existing passes with the same barcode, so we also need to keep that column.

The export file from step 3 probably has more than one pass entry, but we only need to test one (or perhaps a couple of them) pass first.

In other words, we will need to create an import file that looks like this:

pass_barcode,pass_cardNumber
Test-12345-67890,1234567890

Step 5: Import Sample

Create an import job in the temporary application:

The pass from the import CSV will now appear in the list of passes, and we should be able to view it and download into our wallet apps.

Step 6: Prepare for Production

If the test import into the temporary application was successful, everything is now ready to be executed on the actual production application.

When you are ready to import, please contact our support team via the Support Channel and ask for your application to be upgraded to Loyalty v2.

After your app is upgraded, you can go and create the new Pass Template like you did in step 2.

Step 7: Create a Message Template (optional)

Like in the previous version, a Pass Import allows you to send a message to the user that they have a new pass. This is particularly useful after migrating to version 2, because it will allow your users to install a Google Wallet as well as an Apple Wallet item.

Let's create a simple email template that includes the links for both wallet platforms:

The placeholders you can use for version 2 passes are:

• pass_serial the serial number of the pass
• pass_link_apple the link to download the Apple Wallet pass
• pass_link_google the link to download the Google Wallet pass

In order to send updates, we need to include the user in the import CSV:

userID,pass_barcode,pass_cardNumber
test@example.com,Test-12345-67890,1234567890

The user needs to exist in the application of course and (in this example) have an email contact to receive the update message via email.

Step 8: Import and Migrate

Again, to be on the safe side, we would suggest to first import one pass to test if it all works in production too, before you import the bulk of passes and send an update to your users.

Use the migrate option when importing the passes:

The pass will now appear as a v2 pass in our list of passes where we can view it and download it to our wallet apps.

Conclusion

Although there is no automatic migration of passes from Notificare Loyalty v1 to v2, an export/import procedure is here to help you achieve this migration in a pretty straight-forward way. As mentioned several times in this blog post, it is important to always first test with one or more known passes/users before executing a bulk import.

Needless to say, if you need assistance or have any questions, we are available via our Support Channel.