Update the Solution

WSO2 Updates Manager (WUM) is deprecated and will be unavailable from July 2021 onwards. WSO2 Updates is the new tool to include the solution and security improvements that are released by WSO2 Open Banking, on top of a released version. For more information, see WSO2 Updates.

To download and update WSO2 Open Banking, we recommend using WSO2 Update Manager (WUM). Below diagram shows how WUM facilitates this functionality:

This document provides recommendations on updating the solution.

Prerequisite

Before you being, you need to download WUM using your WSO2 subscription. See Setting Up Servers, to find instructions to setup WUM and using it to download/update WSO2 Open Banking.

Using WUM to update the solution

Once you download the WSO2 Open Banking solution, you can get continuous updates via WUM. Let's see how you can get updates:

Grant access to the following endpoints, in case you’re using a firewall/proxy. WUM gets updates by connecting to the https://api.updates.wso2.com and https://cdn.updates.wso2.com endpoints in the WSO2 update service. If your system connects to the update service through a proxy server/firewall, grant access to these endpoints.

Since WUM is a command-line tool, the proxy should be configured from your command-line as follows:

export http_proxy=http://username:password@proxyhost:port/

If you are behind an NTLM proxy, you can use a third party tool like CNTLM to do NTLM proxy authentication. See the CNTLM documentation for instructions.

Change the placeholders and parameters stated using 'x' when executing the following commands.

Run the following commands to check whether there are updates available.

wum check-update <solution>

E.g., wum check-update wso2-obam-x.x.0
E.g., wum check-update wso2-obkm-x.x.0

If an update is available, run the following command to start updating your solution.
```
wum update <solution>

E.g., wum update wso2-obam-x.x.0
E.g., wum update wso2-obkm-x.x.0
```
Your local product repository should now contain the latest and the previous WUM-updated distributions. Let's extract the updates in the latest WUM-updated distribution to a ZIP file.
Execute the following command to identify the previous WUM-updated pack for this solution.
```
wum list [solution-name]

E.g., wum list wso2-obam
```

Execute the following command.

wum diff <Latest-WUM-updated-distribution.zip> <Previous-WUM-updated-distribution.zip>

E.g., wum diff wso2-obam-x.x.0+1538333553548.full.zip wso2-obam-x.x.0+1537333553538.full.zip

The diff ZIP is created in the location from where you executed the diff command.

Open the summary PDF that you get inside this ZIP file (also via email). It contains information about the following:
1. New configurations introduced with the update.
2. Existing files/artifacts that are affected due to the update.
If you do not have any customizations in the existing distribution, simply copy the changed configuration files mentioned in the ZIP to the corresponding directories in your product distribution.
If you have customizations in the existing distribution, there might be conflicts between that and the WUM-updated distribution.

A conflict happens when a customized configuration file or artifact has changed in the WUM updates. As the file/artifact has your customizations in it, it is not recommended to completely replace this file with the file that comes with the update.

Click here to see how to resolve conflicts manually...

File Type	How to Merge the Conflicts
Binary files	Copy all the binary files (.jar, .jks, .car, .war) to the relevant directories in your existing product distribution. If you have made any customizations to .car and .war files, manually merge those changes. Note: If there are .war files in the WUM update, be sure to delete all extracted .war files in your existing product distribution. This is because all deployed .war files get extracted at the server startup and if there are already extracted .war files by that same name, the server will not extract the .war files in the WUM update.
Jaggery files	You cannot replace the Jaggery artifacts in your existing product distribution with the WUM-updated Jaggery artifacts because your existing Jaggery artifacts may contain customizations. Here's how to merge the files: Check the summary PDF to identify how the Jaggery files have changed because of the WUM updates. Apply the changes to the same files in your existing product distribution.
Apply the updated configuration files	Identify the configuration updates in the summary PDF and apply them (by merging) to the relevant configuration files in the `<WSO2_OB_KM_HOME>/repository/conf` and `<WSO2_OB_APIM_HOME>/repository/conf` folders of your existing product distribution. Note: Be sure to merge the configuration files in your environment with the new files. It is not recommended to replace them.
Redundant files	If there are artifacts/files that are removed by the WUM updates, remove them from your existing product distribution.
Newly added files	If there are newly added files listed in the PDF, create the same folder structure (if it doesn't exist) in your existing product distribution and add the file.

Restoring a previous version

When there is an error in the current environment, you might want to roll back the updates and restore the previous stable distribution. To roll back your updates, you need to know which product distribution is currently running in your environment and the previous distribution that was stable. Therefore, it is recommended to keep records of your distributions as a best practice. The previous stable distribution should be stored in your local product repository and should be a fresh ZIP file without any customizations. You can roll back in two ways:

Roll back updates using automation
Roll back updates manually

Roll back updates using automation

If you are using an automation tool such as Puppet, Ansible, or Chef, follow the steps given below.

Apply the previous stable product distribution to your configuration management tool. This should be a fresh ZIP without customizations.
Revert the configurations specific to the updates from the configuration management tool. See the update summary PDF inside the <user_home>/.wum3/products/<solution-name>/<solution-version>/<channel>/<solution-name>-<solution-version>/updates/summary folder to check the configurations that were applied to the environment.
Apply all your customizations to the product distribution. If you are using a deployment synchronization tool, make sure that these customizations are merged in the tool.
Push the product distribution to your environment using the configuration management tool.

Roll back updates manually

Apply the configurations to the previous stable product distribution.
Apply all your customizations to the product distribution. If you are using a deployment synchronization tool, make sure these customizations are merged in the tool.
Push the product distribution to your environment.

Troubleshooting WUM

WUM is a simple command-line tool that you can download and use to get the latest updates for a WSO2 product. To get started from the command line, execute the 'wum --help' command, and the list of available commands and its usage will be explained.

WUM Message	Explanation	Possible Solution
wum: unable to connect to WSO2 Update	The WUM client cannot connect to the WSO2 Update server due to a network failure or the server response is not successful.	Check your network connection. If the connection is still failing, please report to WSO2 at https://wso2.com/contact. Please be sure to attach the details of the error when you report. You can get the details by running the same command again using the '-v' flag.
wum: update is not available in WSO2 Update: <UpdateFileName>	WUM is unable to get updates from the WSO2 Update service due to a server error.	Try running the wum command again. If the command continues to fail, please report to WSO2 at https://wso2.com/contact. Please be sure to attach the details of the error when you report. You can get the details by running the same command again using the '-v' flag.
wum: servers are busy at the moment. Please try again later.	The WSO2 Update server has reached the maximum capacity for handling requests at the current moment.
wum: generating wum file twice. The file '<FileName>' has been added by a previous update. Current update is'<UpdateNumber>'	WSO2 updates are cumulative, which means that once the update files relevant to one particular update are downloaded once to your local update repository, the same update file will not be downloaded again in consequent updates. This error can sometimes (rarely) occur in situations where a cumulative file is erroneously downloaded twice.
wum: invalid update file. Cannot find the update-descriptor.yaml file'<FilePath>'	Some updates dispatched from the WSO2 Update server does not contain the `update-descriptor.`yaml file. This file is stored inside the update file that is downloaded to your local update repository.
wum: unknown form at in the update-descriptor.yamlfile'<FilePath>' reason: <Error Message>	Some updates dispatched from the WSO2 Update server contains an erroneous `update-descriptor.`yaml file. This file is stored inside the update file that is downloaded to your local update repository.
wum: unable to zip directory '<DirectoryPath>' reason: <Error Message>	When you run the 'wum update' or 'wum diff' commands, ZIP files should be created with the relevant distribution/files inside your local product repository. However, prior to creating the ZIP inside the product repository, the original product distribution is copied to a temporary directory location in order to apply the updates. This error occurs if the product distribution (in the temporary location) is deleted prior to generating the new ZIP file.
wum: unable to download updates reason: <Error Message>	WUM is unable to download the updates from the WSO2 Update server.
wum: invalid JWT string to process reason: <Error Message>	The JWT string is not in a valid format.
wum: cannot find the MD5 file of the specified product in WSO2 Update	WUM is unable to find the md5 sum of a file.
wum: unable to generate the update summary. reason: <Error Message>	WUM is not able to generate the update summary PDF for various reasons. When WUM generates a new product distribution ZIP file or a WUM diff ZIP file, a summary PDF file should be generated and stored inside the ZIP file (stored in the local product repository). The updated distribution/ZIP will not be created without the summary ZIP.
wum: invalid update file. Update number of the update file name '<FilePath>' is not equal to update number specified in update-descriptor.yamlfile(<UpdateNumber>)	When WUM generates a new product distribution (ZIP file) or a ZIP file with updates (WUM Diff), your local update repository is checked for updates that have already been downloaded during previous updates. This error occurs when at least one of the update files in the local update repository is invalid, or if it has been manipulated by a user.
wum: invalid credentials	The credentials you provided are not valid. If your WSO2 account was created a short while back, the reason for the login failure may be that your credentials are not synced in the WSO2 Update server.	Try again by providing the correct credentials. If your account was created a short while back, you might have to wait. If authentication is still failing, please report to WSO2 at https://wso2.com/contact. Please be sure to attach the details of the error when you report. You can get the details by running the same command again using the '-v' flag.
wum: you haven't initialized WUM with your WSO2 credentials	You have not initialized WUM. In order to update products, WUM should first be initialized.	You can run the 'wum init' command to initialize WUM using your credentials. See the instructions on initializing WUM for more information.
wum: your session has timed out	The user session has timed out.
wum: unable to read your input reason: <Error Message>	The input value you provided with the wum command is invalid.	Enter a valid input for the wum command and try again. See Getting Started with WUM for instructions on using the wum commands.
wum: file not found	You are attempting to add a product from a specific directory path to the local product repository using the following command: wum add --file <Path_to_product_download>/<product>.zip However, the product file is not available in the directory you specified.	Verify the directory path of the product distribution that you want to add to the repository, and then run the command again.
wum: invalid product filename: <SolutionFileName>	The name of the product distribution that you provided with the wum command is wrong or it does not exist in the local product repository.	Verify the product distribution's name and run the command again.
wum: product <SolutionName-productVersion> is already added	The product version that you are trying to add to your local product repository already exists in the repository.	Try the following: First, delete the distribution from the local product repository using the 'wum delete' command. Then, try adding the product again.
wum: your product distribution '<SolutionFileName>' contains local modifications. MD5 check failed. Please use the original product distribution.	The product distribution that you are trying to update contains local modifications. WUM updates can only be applied to original product distributions (ZIP files) or to original product distributions that have been updated by WUM previously.	Try the following: First, delete the distribution with local modifications from the product repository using the 'wum delete' command. Add a new product. Update the new product you added.
wum: cannot find a matching product for '<Pattern>'	When executing the wum command, the pattern you used to specify the product is wrong.	When you run the wum command, specify the product using a pattern that matches the product name. For example, wso2esb-4.9.0, wso2esb, wso2e etc.
wum: unable to parse the given product pattern '<SolutionPattern>'. reason: <Error Message>
wum: product '<SolutionName-ProductVersion>' is not supported by WSO2 Update.
wum: invalid product '<SolutionName-ProductVersion>'
wum: you are not supposed to set a value for 'repositories.<RepoName>.refreshtoken'	You are using the 'wum config' command to change the refresh token of the product repository (specified in the `config.yaml` file), which is not allowed.	You are not allowed to change the refresh token, access token or any other element related to the local product repository (except the directory location).
wum: you are not supposed to set a value for 'repositories.<RepoName>.accesstoken'	You are using the 'wum config' command to change the access token of the product repository (specified in the `config.yaml` file), which is not allowed.
wum: invalid repository config element '<ConfigElement>'	You are using the 'wum config' command to change an element in the product repository (specified in the `config.yaml` file), which is not allowed.
wum: invalid wumconfig element '<Arguement>' Try 'wum config --help' for more information.	You are using the 'wum config' command to change an element in the product repository (specified in the `config.yaml` file), which is not allowed.
wum: invalid number of arguments Try 'wum config --help' for more information.	The 'wum config' command can only have two valid arguments. You are running the 'wum config' command using more than two arguments.	When you are running the 'wum config' command to change the local product repository location, you should provide both the key and value corresponding to the product repository (specified in the `config.yaml` file) as shown below. wum config local.product.repo ~/<new_directory_path> Key: `local.product.repo` Value: `~/<new_directory_path>`
wum:wumconfiguration is not available.	The WUM configuration file (`config.yaml`) stored in your local `WUM_HOME` directory ( `~/.wum-wso2/`) is not available.	Try executing the 'wum init' command, which will create the configuration file.
wum: unable to get the absolute path of '<Argument>'	The path to the product distribution, which you provided with the following command is not the absolute path: wum add--file <Path_to_product_download>/<product>.zip The relative path is not allowed with this command.	Run the command again using the absolute path to the product distribution, instead of the relative path.
wum: you haven't added any products yet	You are attempting to execute a wum command without adding a product to your local product repository.	Add the needed products to the local product repository by running the 'wum add' command.
wum: cannot validate the target distribution '<SolutionName>-<SolutionVersion>.<Timestamp>'. Some updates required are missing from the local repository, which are found in the target distribution.	You have executed the 'wum diff' command to get the updates between two product distributions. However, some updates, which are included in the newer product distribution (stored in the local product repository) are not available in the local update repository. When a WUM-updated product distribution is created inside the local product repository, the corresponding updates should be stored in the local update repository as well. This error may be because you have modified the contents of the local update repository.	Try the following: First, delete the latest distribution from the product repository using the 'wum delete' command. Generate a new updated distribution using the 'wum update' command. Then, try the 'wum diff' command again.
wum: unable to unzip file '<FilePath>' reason: <Error Message>	You are attempting to update a product using the 'wum add' command, or you are attempting to run the 'wum diff' command. However, the required product ZIP files (in the local product repository) are unable to unzip due to some corruption.	Try downloading the ZIP file again and run the 'wum update' or 'wum diff' command.
wum: local repository path is not available.	When WUM is initialized, your local `WUM_HOME` directory ( `~/.wum-wso2/`) is created, which contains the local update repository and the local product repository. This error occurs if the local product repository's path is missing in the `config.yaml` file.	Update the product repository path in the `config.`yaml file using the 'wum config' command.
wum: unable to delete file '<FilePath>'. Please delete the file manually. reason: <Error Message>	You have executed the 'wum delete' command, but WUM is unable to delete the specified product file.	You can try manually deleting the product file from the local product repository.
wum: unable to download. cannot find a matching product for '<SolutionName-SolutionVersion>'	You have executed the 'wum add' command to download a product distribution and to add it to the local product repository. However, the product name you specified is not available for downloading.	Verify that the product name and version you provide is valid, and try again.
wum: invalid timestamp value '%!d(string=<Timestamp>)'	The timestamp of the update file (stored in the local update repository) or the product distribution file (stored in the local product repository) has been manually changed.	Try providing a valid timestamp and running the wum command again.
wum: invalid product '<SolutionName-SolutionVersion>'. Product version is missing	The pattern used to specify the product does not include the valid product version. When the 'wum update' or 'wum diff' commands are executed, the product name should include the version name.	Try providing a valid product pattern, which includes the correct product version.
wum: username or password cannot be empty	You have executed the 'wuminit' command to initialize WUM without providing values for the username and password.	Give your credentials for the username and password, and try again.
wum: requires a product Try 'wum add --help' for more information.	You have not specified a product with the 'wum add' command. Note that only one product can be specified at a time.	Make sure that the product name is specified when running the 'wum add' command.
wum: requires only 1 product Try 'wum add --help' for more information.	You cannot specify more than one product with the 'wum add' command.	Make sure that only one product is specified with the 'wum add' command.
wum: requires only 1 product pattern Try 'wum check-update --help' for more information.	You cannot specify more than one product with the 'check-update' command.	Make sure that only one product is specified with 'check-update' command.
wum: requires two updated product distributions Try 'wum diff --help' for more information.	You have executed the 'wum diff' command to get the updates between two product distributions. However, you have only provided a single product distribution.	Provide the two product distributions (with different timestamps) that you want to compare, and try the 'wum diff' command again. Be sure to use the product distribution names (including timestamps) accurately.
wum: invalid update distribution names '<Distibution1>' - '<Distibution2>' Try 'wum diff --help' for more information.	You have executed the 'wum diff' command to get the updates between two product distributions. However, the provided product distribution names are wrong.
wum: update levels cannot be the same Try 'wum diff --help' for more information.	You have executed the 'wum diff' command to get the updates between two product distributions. However, you have provided the same product distribution twice.
wum: requires only 1 product pattern Try 'wum list --help' for more information.	You have executed the 'wum list' command to get the list of product distributions management by WUM. However, you have specified multiple products.	Try the 'wum list <solution_name>' command with a single product or try the 'wum list' command to get the list of all products.

You may encounter the following error messages due to permission restrictions at OS-level.

WUM Message	Explanation	Possible Solution
wum: unable to create directory '<Dir>' reason: <Error Message>	WUM is unable to create the specified directory in the relevant location.	Check the permissions (OS-level) for creating folders in the relevant locations. For example, you can enable permission to create folders in the following locations: WUM Home directory. OS-specific temporary directory. Also, check the available disc space and free some space if the available space is insufficient. If the error occurs even after enabling the above permissions, please report to WSO2 at https://wso2.com/contact. Please be sure to attach the details of the error when you report. You can get the details by running the same command again using the '-v' flag.
wum: unable to copy file '<File>' to '<Path>' reason: <Error Message>	WUM is unable to copy the specified file to the relevant path.
wum: Failed to create directory: <DirectoryPath>. reason: <Error Message>	WUM is unable to create the directory in the relevant location.
wum: unable to update LICENSE.txt of the product reason: <Error Message>	WUM is unable to update the `LICENSE.txt` file of the product.
wum: unable to generate update log file. reason: <Error Message>	WUM is unable to generate the update log file (metadata file) inside the local update repository.
wum: unable to store update summary. reason: <Error Message>	WUM is unable to store the update summary PDF in the local product repository. When you execute the 'wum update' or 'wum diff' commands, an update summary PDF file should be generated and stored inside the ZIP file (which is the updated product ZIP, or the ZIP file created with the WUM Diff).
wum: unable to delete the file as adviced in the update '<FilePath>' reason: <Error Message>	When applying updates to the existing product distribution, WUM is unable to delete files in the existing product distribution (as required for the update).
wum: unable to load wum configuration from '<FilePath>'. reason: <Error Message>	WUM is unable to read the `config.yaml` file in order to execute the command.
wum: unable to create wum configuration. reason: <Error Message>	WUM is unable to create the `config.yaml` file in order to execute WUM.
wum: unable to calculate the MD5 of the specified file '<FilePath>' reason: <Error Message>	WUM is unable to calculate the MD5 sum of the specified file.
wum: unable to read directory '<SolutionDir>' reason: <Error Message>	WUM is unable to read the specified directory when running the command.
wum: unable to delete the product: <FilePath> reason: <Error Message>	WUM is unable to delete the specified file when running the command.
wum: Cannot create the temp directory wum-temp. reason: <Error Message>	WUM is unable to create the temporary directory when running the command.
wum: unable to create file '<FilePath>' reason: <Error Message>	WUM is unable to create the file when running the command