iFrame Migration Guide

Overview

This guide covers the migration from integer-based page identifiers to string-based identifiers in the iFrame API. The changes are part of a new navigation structure implementation that provides better organization and access control.

Breaking Changes Summary

⚠️ BREAKING CHANGE: Page ID 10005 (Deductions) has been completely removed and is no longer available.

⚠️ NAVIGATION CHANGES: Some pages no longer display certain navigation links due to the new navigation structure (see individual page notes below).

Migration Timeline

• Current: Both integer and string identifiers are supported (backward compatible)
• Future: Integer support will be deprecated and removed
• Recommendation: Migrate to string identifiers immediately

Page Parameter Updates

Key Changes

• The page parameter accepts integer page IDs (<int>) and is deprecated - will be removed in the future
• The page_name parameter accepts string page IDs (<string>) and is the new standard identification type
• Both parameters are currently supported for backward compatibility
• Some pages no longer show certain navigation links due to navigation restructuring
• New pages have been added to provide granular access to previously linked content

API Request Examples

Recommended (using page_name parameter):

curl --request POST \
     --url /token/user/ \
     --header 'Authorization: Bearer <your-token>' \
     --header 'content-type: application/*+json' \
     --data '{
       "page_name": "employee",
       "email": "[email protected]",
       "roleAccess": 2,
       "customAppClaims": [
         {
           "type": "employeeId",
           "value": "123"
         }
       ]
     }'

Deprecated (using page parameter):

curl --request POST \
     --url /token/user/ \
     --header 'Authorization: Bearer <your-token>' \
     --header 'content-type: application/*+json' \
     --data '{
       "page": 1004,
       "email": "[email protected]",
       "roleAccess": 2,
       "customAppClaims": [
         {
           "type": "employeeId",
           "value": "123"
         }
       ]
     }'

Page Mapping Reference

This table shows the mapping between the deprecated page parameter values (integers) and the new page_name parameter values (strings).

Multi-Admin Role Pages

Admin Role Pages

Note: Every page can also be used by multi-admin role (requires company-id to be defined).

Employee Role Pages

flow Parameter Updates

Named flows provide direct access to specific functionality without navigating through the main pages. Some flows have been deprecated in favor of the new page structure.

API Request Example

curl --request POST \
     --url /token/user/ \
     --header 'Authorization: Bearer <your-token>' \
     --header 'Content-Type: application/*+json' \
     --data '{
       "email": "[email protected]",
       "customAppClaims": [
            {
              "type": "flow",
              "value": "custom-fields-employee-view"
            },
            {
              "type": "company-id",
              "value": 1
            },
            {
              "type": "employee-id",
              "value": 1
            }
        ]
     }'

Available Flows

Deprecated Flows

⚠️ These flows are deprecated and will be removed in a future version. Migrate to the suggested pages immediately.

Migration Example

Before (deprecated):

{
  "customAppClaims": [
    {
      "type": "flow",
      "value": "custom-fields-company"
    },
    {
      "type": "company-id",
      "value": 123
    }
  ]
}

After (recommended):

{
  "page_name": "custom-fields",
  "customAppClaims": [
    {
      "type": "company-id",
      "value": 123
    }
  ]
}