Upgrade from SDK 1.0 to 2.0 (IAM 7.4)
17.3.2.5.2.2. Manual changes for Loginapp REST UI SDK upgrade from UI SDK 1.0 to 2.0 with IAM 7.4

Upgrading the UI SDK from 1.0 as delivered with Airlock IAM 7.3 to UI SDK 2.0 as delivered IAM 7.4 requires some manual changes that are described below.

Those changes may be breaking for scripts or build pipelines that rely on the previous names and conventions. The change for instance.properties is breaking for every IAM instance < 7.4 using this key.

Changes in instance.properties

With Airlock IAM 7.4, the UI SDK ZIP artifact name, path, binary name and key in instance.properties have changed:

SDK 1.0
SDK 2.0
Artifact name and path
Name:
airlock-iam-login-ui-sdk-7.3.zip
Path:
In the build directory relative to the directory where the UI SDK was unzipped to.
Name:
airlock-iam-loginapp-rest-ui-sdk-7.4.zip
Path:
In the build directory relative to the directory where the custom sources were created at using the init command.
Binary name
iam-login-sdk
sdk
Key in instance.properties
iam.loginapp.ui.customizations
iam.loginapp.rest.ui.customizations

When unpacking the artifact for Airlock IAM 7.4, the content is unpacked into this directory:
airlock-iam-loginapp-rest-ui-sdk

Changed i18n format

In Airlock IAM 7.3, the format of the i18n files (located here: src/assets/custom/i18n) was JSON whereas the new format in IAM 7.4 is properties.

  • Customizations to i18n files must be manually migrated by:
  • Renaming the JSON files to properties, e.g. en.json to en.properties .
  • Flattening the JSON structure to the properties format.
  • Example for flattening a JSON structure to properties format
  • We use the content of en.json as an example.

  • 1.
    en.json:
  • { 
        "authentication": { 
            "password": { 
                "title": { 
                    "caption": "Welcome - Please Login" 
                } 
            } 
        } 
    }
  • 2.
    becomes the following in en.properties:
  • authentication.password.title.caption = Welcome - Please Login 
    

Instead of migrating everything by hand, you can find JSON-to-properties converters on the internet that will help you with this transformation.

Changed class concept using ES6 classes in JavaScript

With Airlock IAM 7.4 dropping the support of Internet Explorer 11 (IE11) for the Loginapp REST UI, it is now possible to use JavaScript ES6 classes.

  • This implies various manual changes to existing JavaScript customizations:
  • Inheritance – Using the class and extends keywords instead of var and the extend() method when declaring a class.
  • Constructor – using constructor and invoking the inherited constructor using super() instead of init and this._super().
  • Calling inherited methods – using super.methodName() instead of this._super().
  • Method declaration – it is not possible to use :function when declaring a class method. Also, the comma following the function declaration can be omitted.
  • Splitted iam.api.types.CustomPage into two classes – one for customizing existing product pages iam.api.types.CustomProductPage and one for adding new pages entirely written in JavaScript iam.api.types.CustomJavaScriptPage.
  • Renamed method CustomPage.renderContentHtml to CustomPage.contentHtml .
  • Removed method getPageId which is replaced by isApplicable. This provides more flexibility to customize the same page for different use-cases. If access to the current pageId of your customized page is required, the relevant page data received in the isApplicable({pageId, flowId, stepId}) method has to be stored as class fields.

The following example shows a side-by-side comparison that illustrates the points mentioned above:

Example IAM 7.3
Example IAM 7.4
var MyCustomLayout = iam.api.types.CustomLayout.extend({ 
  
    headerHtml: function () { 
        return '...'; 
    }, 
  
    contentHtml: function () { 
        return '...'; 
    }, 
  
    footerHtml: function () { 
        return '...'; 
    } 
}); 
  
  
var MyCustomPage = iam.api.types.CustomPage.extend({ 
  
    init: function () { 
        this._super(); 
        ... 
    }, 
  
    getPageId: function () { 
        return 'mypage'; 
    }, 
  
    onPageEnter: function () { 
        console.log('entering: ' + this.getPageId()); 
        this._super(); 
    }, 
  
    onPageExit: function () { 
        console.log('exiting: ' + this.getPageId()); 
    }, 
  
    renderContentHtml: function () { 
        return '...'; 
    } 
});
class MyCustomLayout extends iam.api.types.CustomLayout { 
  
    headerHtml() { 
        return '...'; 
    } 
  
    contentHtml() { 
        return '...'; 
    } 
  
    footerHtml() { 
        return '...'; 
    } 
} 
  
  
class MyCustomPage extends iam.api.types.CustomJavaScriptPage { // or iam.api.types.CustomProductPage depending on the use-case 
  
    constructor() { 
        super(); 
        ... 
    } 
  
    isApplicable({pageId, flowId, stepId}) { 
       return pageId === 'mypage'; 
    } 
  
    onPageEnter() { 
        console.log('entering: mypage'); 
        super.onPageEnter(); 
    } 
  
    onPageExit() { 
        console.log('exiting: mypage'); 
    } 
  
    contentHtml() { // Method renamed 
        return '...'; 
    } 
}

Semantic changes to class CustomLayout

In Airlock IAM 7.4, class iam.api.types.CustomLayout changed in its semantic. With IAM 7.3 inheriting from CustomLayout implied that, by default, IAM's product layout was used for header/footer/content except for explicitly overwritten methods. With IAM 7.4, inheriting from CustomLayout does not provide any layout at all.

Custom code that relied on this functionality must be updated to implement the missing methods.

Content HTML requires a marker for actual content placement

In Airlock IAM 7.3, the content HTML was required to be a symmetric structure that was wrapped around the actual Loginapp REST UI content.

With IAM 7.4, it is no longer required for the content to be symmetric. However, the content must define the location where the actual content should be rendered to using HTML ID iamContentTargetContainer.

Example for IAM 7.3
Example for IAM 7.4
var MyCustomLayout = iam.api.types.CustomLayout.extend({ 
  
    contentHtml: function () { 
        return '<div></div>'; 
    } 
  
});
class MyCustomLayout extends iam.api.types.CustomLayout { 
  
    contentHtml() { 
        return '<div id="iamContentTargetContainer"></div>'; 
    } 
  
}

Custom CSS rules that relied on the old HTML structure have to be adjusted accordingly.

Changed availability and naming of custom sass files

The sass files from src/sass/custom are no longer available. These are substituted by _custom-styles.scss and _custom-variables.scss, that can be used to customize the appearance of your application.

IAM 7.3
IAM 7.4
src/sass/custom
_common-styles.scss 
_common-variables.scss 
_instance-styles.scss 
_instance-variables.scss
_custom-styles.scss 
_custom-variables.scss

To preserve your customizations, copy the content of _common and _instance into the corresponding _custom file.

Variables removed from the Loginapp REST UI

The following variables have been removed, since they did not have any effect:

  • iam-form-feedback-valid-color: Loginapp REST UI does not provide feedback for valid inputs.
  • iam-input-box-shadow: Box shadows are by default disabled.
  • iam-btn-box-shadow: Loginapp REST UI default buttons do not support box shadows.