QRadar Applications: Submission Upgrade Path

Introduction

You have published your first Integration, and now you need to submit an update.

This blog post documents the process of how to do so.

Submission Process on the XForce Exchange

Login with your XForce Exchange Account and use the + Add Version process.

Cannot see the previous version when you login to the XForce Exchange?

Please contact your IBM business development lead, so that we can link your XFE account to the submission space for your Integration.

Technical Details

App upgrades will only work if certain values match between the previous version and the new version.

1.     Manifest.txt

2.     Manifest.json ß only application to Integrations with applications

3.     Qradarcontent… xml file

Manifest.txt technical details

Two values are relevant for the upgrade process:

1      The app version

2.      The app ID

The app ID value is derived from the XForce Exchange App ID which you can see in the browser bar

In the manifest.txt file the app ID is listed after the "_id" key

The app version after the "version" key

Manifest.json technical details

Similar to the checks you made in the manifest.txt, you must check the manifest.json. The manifest.json can be found within the app.zip.

Location: root/appcontentfolder/xxxx.zip/manifest.json

Two values are relevant for the upgrade process:

1.      The app version

2.      The app UUID

Check the UUID matches the UUID of the older app and the UUID in the manifest.txt.

Check the version number matches the version on the app card and the manifest.txt.

QRadar content XML file technical details

The final check is to ensure the version number is correct within the _content.xml file. The content.xml files can be found within the app.zip

Location: root/appcontentfolder/_content.xml

Open the _content.xml file

Check the version number matches the version on the app card and the manifest.txt and manifest.xml

FAQ

How do I test upgrades?

Download the published app build from the XForce Exchange

Install this build, then install the new version

Two lines are shown in Admin > Extension Management

If the values in manifest.txt do not match, two extensions will be written to the QRadar database and shown in the UI.

Both the old and new version of the app are visible in the UI

If the values in manifest.json do not match, two application IDs will be written to the QRadar database, two docker containers will be started and two apps will be shown in the UI.

When upgrading "skip" in Extension Management is printed

If the app version in the /_content.xml is not changed, this will occur.

What if I need to support my integration on several QRadar versions?

This is possible, instead of choosing "new version" submit as a new application. When you want to deprecate the older app version, contact IBM Business Development or the App Validation Team, and they will archive the old app.

For several IBM apps, several app builds are published to ensure users on older QRadar versions still can use the app.

However, in this case you MUST edit the manifest.txt as the App ID will not match between Applications.

Between Pulse 7.5.0 Up7+/Pulse 7.5.0 Up3+/Pulse 7.3.0 the XForce Hub ID written to manifest.txt will not be the same.

So, if a user wants to update from Pulse 7.5.0 Up3+ > 7.5.0 Up7+ they will need to uninstall the app OR the developer needs to update the manifest.txt

This is just an example for an IBM application.

If your Integration does not store any data, you can choose to not support upgrades between versions that have two app cards. 

If your integration is an update on the same app card/hub ID, you must support upgrades. Otherwise, users that use the Assistant app will have inconsistency in the upgrade paths.

As otherwise, you must keep editing manifest.txt every time you submit a new version.

Reason: App A > App B, must edit app_id to App A ID. App B gets upgraded, but App ID was edited to App A ID, to ensure App A and App B upgrade.

Process outline for publishing several versions of your Integration 

Submit as a new app

Note that the XForce Exchange UUID will change between the versions, as you have to submit 

Example on changing the manifest.txt

Note: The app version must always increment.

App Exchange UUID for Sample App 7.4.0 UP7+ = abcde
App Exchange UUID for Sample App 7.5.0 UP9+ = 12345
In the manifest .txt for Sample App 7.5.0 UP9+, change the UUID to "abcde".

For the new app card, download the new manifest.txt from the link in Step 2 of the Submission Portal.

Open the manifest.txt and locate the “_id”

Replace the assigned “_id” with the “_id” of the older app.

Check the version number matches the version on the app card.

What if I export the app, but some values do not match?

You can manually update values, however, the signing will be invalid and you will have to re-sign your build.

It is possible that the app code is built locally and now the app UUID in manifest.json does not match.

It is also possible that the manifest.txt was edited before, to allow upgrades.

/_content.xml should always be exported again. If needed, install the fixed built on a QRadar system and export all the Integration content/code again.