Digital Solutions Packages

Digital solutions packages allow you to export and import entire Digital Solutions in one go, enabling easy deployment of complex solutions. A digital solutions package is a deployment package associated with a specific digital solution and contains all the digital assets that are part of that solution.

On digital solutions imports, package integrity validations check for incompatible platform versions or digital assets, to ensure that the local data is not corrupted.

Create Digital Solutions Packages

1. In FintechOS Studio, go to Main Menu > Configuration Management > Digital Solutions Packages.
2. Click Insert.
3. Fill in the Name field, and select the source Digital Solution from the corresponding field.
4. Click Save and Reload. The new digital solution package is now created.
5. The Digital Solution Package Items grid is populated, allowing you to check the digital assets that you want to be included in the package.

Add security configuration to the digital solution package

1. In Settings tab, tick the box for Include Security Configuration to export the security configuration of the digital assets included in the package.
2. From the Deployment Scenario drop-down, choose the action that occurs when importing the digital solution package in another environment:

• Append: the security configuration is added on top of the destination configuration.

  Append does not update

  Currently, the issue is that Append does not update. When importing a package with Deployment Scenario set to Append, existing security role entries in the target environment are not updated. If a security role with the same security role name, entity, and security scope already exists, only completely new combinations are added. Any change to permissions (for example, adding Update to an existing Create, Read setup of a security role) is ignored and will not be reflected after the import, even if Include Security Configuration is enabled and regardless of the Include Extended Security Configuration setting.
  
  For example, if security role SR1 has full rights (Create, Read, Update, Delete) on entity E1 for the Business Unit scope in the source environment, but in the destination environment SR1 already has only Create, Read on E1 for the Business Unit scope, then importing the package with Deployment Scenario = Append will keep the destination at Create, Read and will not add Update, Delete, even though these rights exist in the source.

• Overwrite: the destination configuration is replaced with the one on the digital solution package.

3. Check the Include Extended Security Configuration box to include security configurations that relate to items external to your package but are linked to the same security roles.

   NOTE  
   Items attached to the following default security roles are not exported: Debugger, Developer, Release Manager, Observability, JobServer, User Management. Default security roles must not be used for securing business solutions.
4. When done, click Save and reload.

Configure the custom files mappings

To configure the mappings between digital assets files and portal profiles for custom and custom on-demand files, follow the below steps: 

1. In the Settings tab, click the Configure button to open the Configure Custom Files Deployment page.
2. In the Configure Custom Files Deployment, select the portal profiles where you want to deploy the custom files. Perform this step for each digital asset.
   

Please take into consideration:

• This configuration when exporting a digital solution package is merely a suggestion, it's one way of doing things. When the digital solution package is imported into the target environment, the link between the custom files in the digital solution package and the portals in that environment is prepopulated (provided that the target environment has the same portals as the source environment). However, you can choose any combination before importing.

• The meaning of the Apply to All Portals Without Profile checkbox is that, during import, the respective files are copied to all environments that do not have a portal profile defined (“anonymous” environments). This means they will also be copied to the default Portal and B2C Portal (provided that no portal profile has been assigned to them). If, at any point, other “anonymous” portals are created, these files will be copied there as well.

3. Click Save to keep your selected choices.
4. When finished, click Save and reload.

Once you configure the mappings, you can export the package.

Include identity provider UI themes

The Settings tab of a digital solution package comes with two options in the Identity Provider UI Themes section:

• Include UI Themes: tick to include the UI theme associated with the Portal Profile in the package. The UI theme stored in FintechOS IDP must have the same name as the Portal Profile.

• Stop Package Generation on Themes Retrieval Error: tick to stop the UI theme export if the environment cannot communicate with the FintechOS IDP.

Click Save and Reload after ticking the above boxes for the changes to take effect.

The UI theme should fit the branding or specifications of the project that you are working on. At import, the theme is automatically deployed on the environment based on the portal profile name.

If the package contains 3 portal profiles ("profile1", "profile2", "profile3") and the FintechOS IDP has 2 custom themes ("profile1", "profile2"), when the package is generated it will automatically include the themes named "portal1" and "portal2". The portal profile named "profile3" will not bring a theme into the package as there is no theme named "profile3".

Product Factory Export Settings

These configuration options are for exporting products in a .zip file that also includes files attached to the product, such as: images, pdf files, etc. Such an example would be a credit card financial product together with the image to be imprinted on the physical card.

This section has the following options:

• Include Configuration: it is unchecked by default. Check it to include Product Factory configuration at package export.

• Stop Package Generation On Product Factory API Error: is it checked by default. It controls the export behavior if an error is encountered when exporting products or the product security configuration:

  • If checked, then the export process is stopped and an error is shown.

  • If unchecked, if an error is encountered a warning will be logged and the export process will continue. The products that generated the error won’t be exported.

You can find the actual product in a folder under Products, with the product code. It also contains the product.json file and the assets folder with the product files, such as images.

APIs for Export Settings

To further support the improved export settings, you can use a new V2 version of the products import/export APIs:

• baseAPIUrl/pfapi/api/v2/products/export: exports the product definitions by their product IDs or codes in a JSON file format within a zip archive. This zip archive can be used as a prerequisite for importing product data into another system. The product IDs or codes should be obtained from product edit or view pages.

• baseAPIUrl/pfapi/api/v2/products/import: imports the product definitions from a zip archive. The zip archive should be in the format produced by the export function.

To use these, you must add the API URL in the following Configuration Manager key: /environment-context/InternalPFApiUrl. Example below:

/environment-context/InternalPFApiUrl: https://your-environment/pfapi/api/

Export Digital Solutions Packages

1. In FintechOS Studio, go to Main Menu > Configuration Management > Digital Solutions Packages.
2. Select the desired package.
3. Click Export Digital Solution Package.
4. Choose the save location of the package. The digital solution package is exported in a .zip file.

Import Digital Solutions Packages

Follow the below steps for an automated import process at digital asset level.

1. In FintechOS Studio, go to Main Menu > Configuration Management > Digital Solutions Packages.
2. Click Import digital solution package. A window is displayed.
3. Locate the .zip file containing the package, select it, and click Import. A wizard window with three tabs displays:
   
• Solution Validation: shows a summary of the digital assets included in the package.
  
• Digital Assets: specify the destination of the digital assets. Add them in an existing Digital Solution or in a new one. Click Next once done.
  
  
• Import Setting: specify settings:

  • In the Identity Provider UI Themes section:

    • if the Include UI theme option is ticked, then all themes present in the package are uploaded to the IDP by overwriting existing themes (if there are theme sharing same name) or new ones are created.

    • use the Stop solution import on themes save error option to stop the package import if the platform cannot communicate with the IDP.

  • In the Scenario for order index import section, pick an option from below so that all entities with an order index keep the correct ordering in the target environment and you avoid manual reordering after deployment:

    • Append: inserts new items from the package at the end of the existing list in the target environment. The order index values of the existing items are updated using the values from the package.

    • Overwrite: (default): the target environment adopts the ordering from the package. Items included in the package get the order index values according to the package, while any items that are only in the target environment are shifted down, preserving their relative order.

      How it works:

      • When package items have duplicate order index values, the platform does not allow these duplicates and does not break the import process; instead, it applies the fallback scenario Append to handle them.

      • You can import a dashboard package using Overwrite when the target environment already contains some of the items from that package and the package also introduces a new dashboard that uses a new OrderIndex value.

      • Using overwrite, you can import packages with dashboards containing overlapping and new order index values.

      • the import process properly validates element order indexes against the maximum order index available in the target environment.

      • You can import with Overwrite or Append on environments where max order index values for the Menu Items is smaller than the order index of the Menu Item from package.

      • When importing a package into an environment using Append, and then import the exact same package again into the same environment using Overwrite, the Order Index (OI) values from the database are not updated to match the OI values from the package. In other words, after this scenario, the Order Index in the destination environment remains unchanged instead of reflecting the Order Index as defined in the package.

      • In Overwrite mode, existing items found in the package are reordered to match the order index from the package, and any new items from the package are then added according to that same order. Example:

        • Source: A – OI1, B – OI2, C – OI3

        • Overwrite (package): Test1 – OI1, C – OI2, A – OI3, B – OI4

        • Result: C – OI1, A – OI2, B – OI3, Test1 – OI4

  • select the Deploy audit configurations box if needed.

  

The package is imported and can also be viewed in the Digital Solution Packages List.

Considerations at package import:

• Because of the differential deploy feature in FintechOS Studio, when reimporting a package with changes, files are marked accordingly with the Update or New status, making it easy to see which files have been changed since the last import.

• When importing a package that includes an updated entity form into a target environment where an older version of that form already exists, the system checks its child files—such as entity extensions, filtered fields, allowed attributes, and virtual attributes. If these child files haven't changed and match those in the imported package, they won't be re-imported.

• An error may be triggered after importing a package with a renamed extended model. This is a known issue in the following scenario:

  • on a source environment, create two entities with lookup attribute between them. Create a new extended model of type Related and add the virtual attributes to this extension. Export the package and import it to a destination environment. The import should work.

  • return to the source environment and modify the name of the extended model. Export the package with an updated name and reimport it on the destination environment. The import will fail with an error message.

    The workaround implies using a before import script that will map the entity extension before package import:

var ee = ftos.data.query.getAlias("entityExtension")

var rows = ftos.data.query.from('entityExtension', ee)
.where(ee.Name.eq('ext_rel'))
.executeAndMapComplex({entityExtensionId : ee.EntityExtensionId})

if(rows.length > 0){
    setMessage(rows[0].entityExtensionId)
    setMessage("Record found. Will update");
    update('entityExtension', rows[0].entityExtensionId, {"name":"ext_rel_update"})
}
else{
    setMessage("Record not found.");
}

Delete a Digital Solution Package

1. In FintechOS Studio, go to Main Menu > Configuration Management > Digital Solutions Packages.
2. Select the desired package and click Delete. A confirmation dialog is displayed.
3. Click Yes to remove the Digital Solution Package.

The package is deleted and can no longer be viewed in the Digital Solution Packages List.

Deployment Scenarios

When exporting digital solution packages from one environment and importing them into another, several use cases may arise, especially when considering the security roles and security role items involved in each environment, entities, as well as the available package export settings in the FintechOS Platform.

In the scenario below, we start from a scenario where the solution package has certain security roles and security role items on certain entities.

When importing the package to the destination environment, several things must be taken into consideration:

• the security role item (SRI) is on the entity 3 (E3) on the source environment, but on the E1 on the destination environment;

• several SRIs are brought on to existing entities on the destination environment;

• SRI-35 is on E3 on both environments.

Find below a visual representation of this scenario:

Source Environment                                                            
                ├── Security Role: SR1
                │   ├── SRI-11 → E1
                │   ├── SRI-12 → E1
                │   └── SRI-14 → E3
                │
                └── Security Role: SR3
                    └── SRI-35 → E3
      
      
                Destination Environment (before import)
                ├── Security Role: SR1
                │   ├── SRI-12 → E1
                │   ├── SRI-14 → E1
                │   ├── SRI-15 → E4
                │   ├── SRI-16 → E3
                │   ├── SRI-24 → E3
                │   └── SRI-25 → E5
                │
                ├── Security Role: SR2
                │   └── SRI-22 → E1
                │
                └── Security Role: SR3
                    ├── SRI-35 → E3
                    ├── SRI-38 → E3
                    └── SRI-39 → E5

Depending on existing settings in the FintechOS Platform, several use cases emerge:

Use case 1

When creating the digital solution package, if the following options are used:

• Include Security Configuration box is ticked;

• Include Extended Security Configuration is not ticked.

Then the following are included in the export package:

Copy

├── Security Role: SR1
│   ├── SRI-11 → E1
│   ├── SRI-12 → E1
│   └── SRI-14 → E3
│
└── Security Role: SR3
    └── SRI-35 → E3

Use case 1.1

If, additionally, we select Append, then when importing to the destination environment, the roles that don't already exist are added, and existing ones are not modified.

The result would be:

Copy

Destination Environment (after import)
        │
        ├── Security Role: SR1
        │   ├── SRI-11 → E1
        │   ├── SRI-12 → E1
        │   ├── SRI-14 → E1
        │   ├── SRI-15 → E4
        │   ├── SRI-16 → E3
        │   ├── SRI-24 → E3
        │   └── SRI-25 → E5
        │
        ├── Security Role: SR2
        │   └── SRI-22 → E1
        │
        └── Security Role: SR3
            ├── SRI-35 → E3
            ├── SRI-38 → E3
            └── SRI-39 → E5

Use case 2

In this use case, the conditions are the following:

• Include Extended Security Configuration box is ticked;

• The digital solution is slightly changed:

  Copy

  ├── SR1
  │   ├── SRI-11 → E1
  │   ├── SRI-12 → E1
  │   └── SRI-I4 → E3
  │
  ├── SR3 (with or without)
  │   └── SRI-35 → E3
  │
  └── SR6
      └── [New security role created outside the Digital Asset context]

Usecase 2.1

If we select Append and keep the Include Extended Security Configuration selected, then when importing to the destination environment, the security configuration is added on top of the destination configuration:

Copy

├── SR1
│   ├── SRI-11 → E1
│   ├── SRI-12 → E1
│   ├── SRI-14 → E1
│   ├── SRI-I4 → E3
│   ├── SRI-15 → E4
│   ├── SRI-16 → E3
├── SRI-24 → E3
│   └── SRI-25 → E5
│
├── SR2
│   └── SRI-22 → E1
│
├── SR3
│   ├── SRI-35 → E3
│   ├── SRI-38 → E3
│   └── SRI-39 → E5
│
└── SR6

Usecase 2.2

If we select Overwrite and keep the Include Extended Security Configuration selected, then when importing to the destination environment, the destination configuration is replaced with the one on the digital solution package:

Copy

├── SR1
│   ├── SRI-11 → E1
│   ├── SRI-12 → E1
│   ├── SRI-I4 → E3
│
├── SR2
│   └── SRI-22 → E1
│
├── SR3
│   ├── SRI-35 → E3
│
└── SR6
                            

• For SR1 (entities E1 and E3): the security role items associated with these entities will be replaced with those from the exported package. An overwrite is performed using the new information from the package.

• For SR2 and SR6: no changes will be made, as the exported package does not contain these roles. The definitions from the source package will be retained.

• For SR3: an overwrite will be performed only for the packages associated with entity E3, since the exported package does not contain security role items defined for E5.

In summary, an overwrite will be performed only for those roles and security role items that are associated with entities present in the exported package.