¶ Package Manager
The Package Manager is a tool for exporting and importing settings of the whole API provider – all entities, operations, variables and settings in one package that can be easily transfered to another environment.
¶ Manual Export/Import
You can manually export or import API provider with Actions / Export RWU or Actions / Import RWU:
- Export will provide you with the .rwu file containing all provider operations and settings (save some environment specific data).
- You can import this file to another environment. The import will create or update a provider with the same Description.
- Environment specific data like API keys must be manually set in the target environment and package update will not change these values.
- Package import will create a new line in package manager if applicable (i.e. the package is publicly available for download). You can use it to update the package to latest version later.
The .rwu file does not contain any RapidStart packages. If your provider uses them, you need to import these packages first or import the whole .zip provider package (see Package structure and versioning).
¶ Provider Settings
There are some additional settings related to the package manager in provider details. To access them, select your API provider from the list and open Details:
- Provider Version is the current package version. It can be imported with package manager or from the .rwu file – or you can set it manually when creating the package.
- Minimal Compatible App Version is the minimum extension version, that is required for current package. This parameter should be used in extensions that rely on some provider package (e.g. Balikobot) to force the user to update the package or extension if needed. You can set this field manually or use action Update Last Compatible Extension Version to get the current extension version (see Code Samples to learn how to implement this in your extension).
- Certified Provider marks Navisys certified provider packages.
¶ Package Manager
To access the package manager select Actions / Package Manager from the menu:
Here you can see the list of your currently installed packages. Please note that this may not be all of your packages, because you can create new ones manually too.
- Provider Name / Provider ID Enum – Identifies the API provider, that should be updated or created from the downloaded package.
- Installed Version – Current installed package version.
- Repository URL – Publicly accessible URL of the repository with provider packages.
- Package Name – Code of the provider package.
- Base Package Version No. – Version no. of the base package, that can be used for automatic installation (e.g. during extension setup).
¶ Download Update
- You can check if there is a newer version available with action Check for Updates.
- Action Download Update allows you to download and install the requested provider package. This will open a dialog:
You can either choose to download the latest package version (recommended in most cases), or ask for a specific version of the provider package.
¶ Environment Specific Data
Some settings are applicable only in current environment. If some API service provides you with an API key, you probably have different one in test and production environment. RESTwithUS handles this kind of data in a following way:
- These settings can contain sensitive information, so they are not included in the .rwu package file at all.
- If you are importing a new package, you have to fill the parameters manually in the target environment.
- Any further package update will not touch these values, they stay as they are.
Environment specific data are:
-
User Name and Password for Basic authentication, and provider Log settings in provider Details:
-
Provider Variables with checked option Do not Overwrite Value (this is the place for storing API keys etc.). If the field is not checked, the variable will be overwritten on package update.
-
Synchronization timestamps on entity level:
-
Any Connections or Batch Entries in the target environment. Package update can change the definition of an entity or an operation, but does not touch existing connections with an external system or saved batch entries. They will be associated with the updated entity or operation.
¶ Package Structure and Versioning
Packages that are downloaded with package manager are in the .zip format. The zip file contains:
- Any RapidStart packages used by the provider. These packages are imported first (but they are not applied). Since RESTwithUS cares only for the tables and fields settings, it's best to export the packages without any data to reduce loading times.
- The .rwu file or files with provider settings.
When checking for newer version or downloading it, package manager uses Repository URL and Package Name fields:
- By default, Check for Updates and Download Update actions always check for the latest version, so for example the final URL for provider
Test Providerwould be: https://rwu.blob.core.windows.net/rwutest/TESTPROVIDER-Latest.zip. - If you select a specific version during the update dialog, the URL will change and will contain the required version: https://rwu.blob.core.windows.net/rwutest/TESTPROVIDER-19.0.0.0.zip.
¶ Code Samples
¶ Download and Install Provider Package
var
APIPackageManagerRWU: Record "API Package Manager RWU";
APIScriptRWU: Codeunit "API Script RWU";
ProviderID: Enum "Provider ID RWU";
APIPackageManagerRWU.SetRange("Provider ID Enum",ProviderID::"Test Provider");
APIPackageManagerRWU.FindFirst();
//Download latest package version
APIScriptRWU.TRY_INSTALL_LATEST_PACKAGE(APIPackageManagerRWU, false);
//Download specific package version
APIScriptRWU.TRY_INSTALL_SPECIFICVERSION_PACKAGE(APIPackageManagerRWU, '19.0.0.1', false);
¶ Get Last Compatible Extension Version
If you want to use the Update Last Compatible Extension Version action on the provider card, you need to register to the GetProviderExtensionAppVersion event.
codeunit 50000 "API Package Mgt. Event Handler"
{
SingleInstance = true;
[EventSubscriber(ObjectType::Codeunit, Codeunit::"API Package Management RWU", 'GetProviderExtensionAppVersion', '', false, false)]
local procedure GetProviderExtensionAppVersion(
_APIProviderName: Text;
_ProviderIdEnum: Enum "Provider ID RWU";
var _ExtensionVersion: Text;
var _Handled: Boolean);
var
AppInfo: ModuleInfo;
begin
if _ProviderIdEnum in ["Provider ID RWU"::"Test Provider"] then begin
NavApp.GetCurrentModuleInfo(AppInfo);
_ExtensionVersion := Format(AppInfo.AppVersion);
_Handled := true;
end;
end;
}
Tip: This code will always get the current version of your app. If you want to use the same package version for all Business Central versions (
18,19etc.), you may generate the_ExtensionVersionby yourself.
¶ Create Package Manager Entry during Extension Installation
codeunit 50001 "Install Mgt."
{
Subtype = Install;
trigger OnInstallAppPerCompany()
var
AppInfo: ModuleInfo;
begin
// Code for Database related operations
// Get info about the currently executing module
NavApp.GetCurrentModuleInfo(AppInfo);
// A 'DataVersion' of 0.0.0.0 indicates a 'fresh/new' install
if AppInfo.DataVersion = Version.Create(0, 0, 0, 0) then
HandleFreshInstall(true)
else
// If not a fresh install, then we are Re-installing the same version of the extension
HandleReinstall(true);
end;
local procedure HandleFreshInstall();
var
UpgradeTag: Codeunit "Upgrade Tag";
begin
// Do work needed the first time this extension is ever installed for this tenant.
// Some possible usages:
// - Service callback/telemetry indicating that extension was installed
// - Initial data setup for use
// SetAllUpgradeTags raise event OnGetPerCompanyUpgradeTags so it register all custom upgrade tags
UpgradeTag.SetAllUpgradeTags();
InstallPackageManager();
end;
local procedure HandleReinstall();
begin
// Do work needed when reinstalling the same version of this extension back on this tenant.
// Some possible usages:
// - Service callback/telemetry indicating that extension was reinstalled
// - Data 'patchup' work, for example, detecting if new 'base' records have been
// changed while you have been working 'offline'.
// - Setup 'welcome back' messaging for next user access.
InstallPackageManager();
end;
procedure InstallPackageManager()
var
APIPackageManagerRWU: Record "API Package Manager RWU";
APIPackageManagerRWU2: Record "API Package Manager RWU";
APIScriptRWU: Codeunit "API Script RWU";
ProviderRepositoryURLTok: Label 'https://rwu.blob.core.windows.net/rwutest/', Locked = true;
ProviderPackageNameTok: Label 'TESTPROVIDER', Locked = true;
ProviderBaseVersionTok: Label '19.0.0.0', Locked = true;
begin
APIPackageManagerRWU2.Reset();
APIPackageManagerRWU2.SetRange("Provider ID Enum", "Provider ID RWU"::"Test Provider");
if APIPackageManagerRWU2.IsEmpty then
APIScriptRWU.CREATE_PACKAGE_MANAGER_LINE("Provider ID RWU"::"Test Provider", ProviderRepositoryURLTok, ProviderPackageNameTok, ProviderBaseVersionTok, APIPackageManagerRWU);
end;
}
Do not call TRY_INSTALL_LATEST_PACKAGE or TRY_INSTALL_SPECIFICVERSION_PACKAGE during the extension installation if your provider contains RapidStart packages. Create a separate function for package installation and call it during extension setup instead.
¶ Download and Install Package
procedure DownloadRWUConfiguration(_Provider: Enum "Provider ID RWU")
var
APIPackageManagerRWU: Record "API Package Manager RWU";
InstallMgt: Codeunit "Install Mgt.";
begin
APIPackageManagerRWU.SetRange("Provider ID Enum", _Provider);
if APIPackageManagerRWU.IsEmpty then
InstallMgtBLKRWU.InstallPackageManager();
APIPackageManagerRWU.FindFirst();
APIPackageManagerRWU.DownloadUpdateWithDialog();
end;
¶ Update Package Manager Entry during Extension Update
codeunit 50002 "Upgrade Mgt."
{
Subtype = Upgrade;
var
InstallMgt: codeunit "Install Mgt.";
trigger OnUpgradePerCompany()
begin
InstallMgt.InstallPackageManager();
end;
}