How to upgrade NavSherpa to AL

This guideline should help you migrate NavSherpa from C/AL to AL in a fairly complicated scenario:

You have existing list and library setups in C/AL, each one with already uploaded documents.
Some tables and fields used in the setups has a different ID in AL.
Some records with attached documents were moved to another table.

In a less complicated scenario (e.g. you do not need to transfer document mappings) just skip some of the following steps.

Prerequisites

Your C/AL NavSherpa must be upgraded at least to the version NSPW114.00.07.
If you need to update some table and field IDs during upgrade, AL Extension NavSherpa must have at least version 22.03.00, 23.02.00 or 24.01.00.
AL NavSherpa requires a different license key than C/AL version. If you are migrating from C/AL BC 140, please order your extension NavSherpa license first.

Preparations in BC 140 (C/AL)

NavSherpa version 14.00.07 adds a new field NAV Record Position to SharePoint Document Mapping, SharePoint Record Mapping and SharePoint Workflow Mapping tables. This field stores related BC record ID in a text form and is used to match the mapping with a correct BC record in AL.

This field is blank at first, you need to fill it by running report NavSherpa Update Record Pos. (from the DEV environment) for all afftected list/library setups.

Upgrade function

The upgrade function is meant to run automatically during upgrade and fix the data, that are wrong for some reason. You will need it if some tables and fields have a different ID in C/AL - otherwise you can skip this step. For more details about upgrade code see Microsoft documentation: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-upgrading-extensions.

We recommend to set up an upgrade tag to prevent the upgrade code to run more than once.

procedure GetNavSherpaUpgradeToAL(): Code[250]

begin

exit('NavSherpaUpgradeToAL-20240129');

end;

The upgrade function mainly uses UpdateTableAndFieldIDs from the NavSherpa Interface codeunit. This function goes through the list/library setups with affected BC table and updates the table and field IDs in all related records. The upgrade function can look as follows.

procedure UpgradeNavSherpaToAL()

var

NSPInterface: Codeunit "NSP Interface";

UpgradeTag: Codeunit "Upgrade Tag";

FieldIDs: Dictionary of [Integer, Integer];

begin

if UpgradeTag.HasUpgradeTag(GetNavSherpaUpgradeToAL()) then

exit;

//Table has new ID in AL, but the field IDs did not change

NSPInterface.UpdateTableAndFieldIDs(90828, 55028); //Asset Check Header

//Table has new ID in AL and some fields has a different ID, too

Clear(FieldIDs);

FieldIDs.Add(90819, 106); //Active

FieldIDs.Add(90820, 107); //Implementer By PR Type

NSPInterface.UpdateTableAndFieldIDs(90813, 55013, FieldIDs);

//Table has new ID in AL and some fields has a different ID, too + this transformation should be called only for some list/library setups

Clear(FieldIDs);

FieldIDs.Add(90819, 106); //Active

FieldIDs.Add(90820, 107); //Implementer By PR Type

NSPInterface.UpdateTableAndFieldIDs(90813, 55013, FieldIDs, 'INCDOC_DOCS|INCDOC_LIST');

//Table has the same ID in AL, but some fields in a table extension has a different ID

Clear(FieldIDs);

FieldIDs.Add(90876, 55007); //UPN Login

NSPInterface.UpdateTableAndFieldIDs(5200, 5200, FieldIDs);

//Set the upgrade tag and commit the data

UpgradeTag.SetUpgradeTag(GetNavSherpaUpgradeToAL());

Commit();

end;

Manual Steps

After you finish the data migration and data upgrade, there are a few manual steps that you need to do to get NavSherpa running in AL.

Important: Before going live, make sure, that you disabled all automatic jobs in your BC 14! You certainly do not want two Business Central instances connecting and uploading files to one SharePoint.

New License Key

If you are migrating from Business Central 14 (C/AL version), your NavSherpa license key will not work with AL extension version. Please order the extension license key in advance and after migration enter the correct license key in NavSherpa Setup. Ensure that the license is valid for your VOICE account number.

Authentication

If you were using any other than OAuth authentication, you need switch to it now. Please have a look at the installation tutorial videos or NavSherpa help and run the Setup Access Token wizard to set it up.
When using OAuth authentication, you may need to refresh the access token.

Please open your root SharePoint site setup and check the connection by selecting the Author SP Field Internal Name. If you can see the list of fields from SharePoint, your connection is ok and you can proceed to the next step.

Run NavSherpa data upgrade to AL

Go to NavSherpa Setup and run action Start Data Upgrade to AL (run this action in each company, where you have NavSherpa). This will perform the last steps that are needed to update the data to AL version. If something goes wrong, fix the errors and run the action once more.

Note: Without the NavSherpa data upgrade there are some vital information missing in SharePoint List Setup table and your NavSherpa will not work properly.

Start NavSherpa Automatic Job

As the last step, create or start the job queue entry responsible for NavSherpa automatic jobs.

Important: Please ensure, that the automatic job in your old database is stopped by now and no users are adding documents there!