Migrating your Developer Portal from Version 5 to Version 2018

Guidance on how to migrate a Developer Portal site from IBM® API Connect Version 5, to IBM API Connect Version 2018.

In IBM API Connect Version 2018 the Developer Portal is based on the open source Drupal 9 content management software, which enables more advanced, flexible, and powerful customization capabilities. However, in IBM API Connect Version 5 the Developer Portal is based on Drupal 7. The migration tooling in Version 2018 will create a new Developer Portal site, and migrate all of the associated APIs and Products, user information, and subscriptions over. However, customizations such as modules and themes cannot be automatically migrated, as the Drupal 9 baseline is very different to Drupal 7. For more information about upgrading from a Drupal 7 baseline to a Drupal 9 baseline, see Upgrading Drupal in the Drupal documentation.

The following sections take you through the migration process for the Developer Portal, and provide guidance on how to manually migrate any specific customizations to Drupal 9.

Migration process for the Developer Portal
Portal Delegated User Registries
Custom themes
Custom modules
Custom Rules
Custom content types and fields
Advanced theme development
Changing the page layout
Changing the front page
Features no longer available in the Developer Portal

Note: The ability to migrate is available only from IBM API Connect Version 5.0.8.7 onwards. If your deployment is at an earlier version, you must upgrade before migrating. See Upgrading your API Connect cloud for information about upgrading in Version 5. For more information about the supported versions for migration, see Migrating a Version 5 deployment to Version 2018.

Migration process for the Developer Portal

The migration process for the Developer Portal migrates all of the following information to Version 2018 for each site in your cluster:

User information (if Portal Delegated User Registry is enabled, the process is slightly different; see Portal Delegated User Registries).
Products and APIs.
Consumer organizations.
Applications.
Subscriptions.

For information about the main migration process, see Migrating a Version 5 deployment to Version 2018.

Portal Delegated User Registries

If your IBM API Connect Version 5 Developer Portal uses Portal Delegated User Registry (PDUR), you must first export the user information that is stored in the Version 5 Developer Portal local database. This user information can then be fed into the migration tooling so that the correct user registries can be created in Version 2018.

For more information, see Exporting Portal Delegated User Registry user information.

Custom themes

If your Version 5 Developer Portal is using a custom theme, you'll need to create the custom theme again for the Drupal 9 baseline. Start by creating a sub-theme of the new Version 2018 Developer Portal site by using the theme generator, and then manually customize the sub-theme to your specifications for Drupal 9 by using Cascading Style Sheets (CSS), or Sass CSS (SCSS). Note that using SCSS in your theme makes it far simpler to change colors. We've also added a color template theme generator, which means you can quickly generate a base color theme on which to build your customized site branding. For more information, see Creating a sub-theme.

Note, directly editing the API Connect theme is not permitted or supported, as edited versions of these files are overwritten when a fix pack or iFix is installed.

Other useful resources:

Tutorial: Creating a custom theme for the Developer Portal - takes you through how to use the theme generator, customize a theme, and install a custom theme.
Changing the site logo - how to change your site logo.
Changing the shortcut icon - how to change the shortcut icon (favicon).
Creating sub-themes - Drupal documentation about creating sub-themes.
Theming differences between Drupal 6, 7 & 8 - Drupal documentation about theming differences.

Custom modules

If your Version 5 Developer Portal is using any custom modules, you will need to create these custom modules again for the Drupal 9 baseline. For more information on writing custom modules, see Extend.

Other useful resources:

Creating custom modules - Drupal documentation about creating custom modules.
Getting started creating custom modules - Drupal documentation giving background information and prerequisites needed for custom module development.
Understanding hooks - Drupal documentations about hooks.
Drupal API hooks - Drupal documentation about the hooks that are available.

Custom Rules

If your Version 5 Developer Portal is using any custom Rules, you will need to create them as custom modules for the Drupal 9 baseline. You cannot export the Drupal 7 Rules, and then import them into the Drupal 9 baseline, as the events and actions are implemented in a different way. For more information about custom modules, see the section about Custom modules.

Custom content types and fields

If you've created custom content in your Version 5 Developer Portal, you can export the following custom content types:

Any custom fields added to APIs, Applications, Products, Consumer Organizations, or users.
Any custom image files for Applications, APIs, or Products.
Any attachment files added to APIs or Products.

When the migration tooling is available, you can then import this content into your Version 2018 Developer Portal. For information about exporting custom content from Version 5, see How to export custom Developer Portal content.

Any other custom types or fields content that you've created in Version 5, will need to be created again for the Drupal 9 baseline. For information about creating custom content types, see the following topics:

Advanced theme development

If your Version 5 Developer Portal is using modified content type templates, you must create these templates again for the Drupal 9 baseline. In Drupal 9 the templates are Twig files that define the actual HTML output for a particular piece of content. You can override a Twig template by copying the original template into the templates folder of your custom sub-theme, and then editing the template to your specification. The Developer Portal then uses your template in preference to the original one. For more information, see Applying a modified content type template, and Creating a sub-theme. You can also follow a guided example of how to create a new theme, see Tutorial: Creating a custom theme for the Developer Portal.

Note:

Modifying Twig templates allows very fine-grained control over the structure of pages. However, it also means you might miss new features and defect fixes that are made to the original templates, as your Developer Portal is using your overrides instead of the originals. So, if you override a template, it is your responsibility to check the templates in the latest API Connect Version 2018 releases, and to ensure that any equivalent changes that are needed to your overrides to maintain functional equivalence are made.

Changing the page layout

If your Version 5 Developer Portal is using a different page layout, you will need to create this layout again for the Drupal 9 baseline. The page layout is defined by configuring which blocks appear in which regions. Blocks are controlled by using the Structure > Block layout options on the Developer Portal administrator dashboard.

For information about how to configure the page layout, see Adding and changing the blocks displayed on Developer Portal pages.

Changing the front page

If your Version 5 Developer Portal is using a different front page, you will need to create this front page again for the Drupal 9 baseline. The front page is configured from the Structure > Pages options on the Developer Portal administrator dashboard.

For information about how to configure the front page, see Configuring the front page, and Adding custom pages.

Further options that you might want to consider when designing your front page include:

Change the banner block content or image: Changing the front page banner block.
Display featured API Products by creating a featured content block: Changing the front page Featured Content block.
Create custom blocks with your own HTML content: Adding and changing the blocks displayed on Developer Portal pages.
Set up the social block to include your organization Twitter feed: Integrating Twitter data into the social block.

Features no longer available in the Developer Portal

The following features that are available in IBM API Connect Version 5, are not available in IBM API Connect Version 2018:

Security questions - these can now be created inside an OpenID Connect provider.
Two-factor authentication - this can now be performed inside an OpenID Connect provider.
Support tickets - no Drupal 9 equivalent module is currently available.