Import and export an application

This page describes the different export/import use cases, as well as how to import and export applications from a deployment.

Characteristics of a backup/export file

An export file has an .appx extension, it reflects the state of the application in the exported version, and typically contains:

  • The application properties and its spaces.
  • The model of the application, the entities with their attributes, the rhythms, and the classifiers 
  • The images and the icon sets
  • The perspectives, the dashboards, the pagelets and the style templates 
  • The security configuration (application permissions,  space permissions, and roles)
  • All instances of configuration entities (global singleton, for example the Process entity or the Steps ...)

An export file does not contain monitored objects (instances of transaction entities).

Full export vs partial export

A full export is a complete backup of the application with the content of all its spaces (hidden or not)

A partial export contains only the content of a subset of the spaces of the application, based on user selection.

Use cases for exporting an application

In Decision Insight, you can export an application because:

Export an application for backup

Exporting an application for backup is very easy. In this case, you want to save the state of your entire application for backup purposes. For more information, see Backup an application.

Migrate part of the same application from one deployment to another. 

Suppose you are working on a deployment, and a colleague is working on another deployment of the same application. You want to share the route that you've designed so your colleague can use it.

Step Action
1

From the source deployment, on the main menu, click the Configuration   icon. On the left menu, click Application in the Administration section.
2

Click the Export button.
3

Select only the space that contains the information you want to migrate to the other deployment, for example, the routes space.
4

Click Export. An .appx file of your application is produced.
5

In the destination deployment, import the .appx file.

Reminder

On a standalone deployment, this means, import the file to the one node that you have. On a primary/replica cluster, import the file to the destination primary node. The destination deployment is updated with the route from the source deployment.

Upload an application to another deployment

To upload an application to another deployment, simply export the application the same way you create a backup, then import it to the other deployment:

  • For a standalone deployment, you simply import the application to your one node. 
  • For a complex deployment with a primary/replica cluster, you import the application to the primary node of the cluster. 

Now that a Decision insight deployment can only host one single application, you can face the two following cases:

  • The exported source application and the target deployment application are the same. The target application is updated with the export content.
  • The target and source application are not the same. The source application content is merged into the target application.

Clean the contents of the application

Do not attempt on production environments without testing

This task is for users who want to remove elements of the application from their production environment. It is not recommended to try to clean an application content on a production environment. Proceed with caution. You must test this on a pre-production environment first.

Currently, it is not possible to delete some of the elements of an application directly from the user interface, for example, entities, keys, spaces, rhythms, etc.

During the development phase of your deployment, you may have created many elements for testing purposes and that you now want to remove from the application when you import it to your production deployment. 

In the same way, you may have a production environment that contains obsolete or unnecessary data. To clean the production application, first do a full export of the application to your dev or testing environment. Once you've cleaned your application, you can re-import it back to your production environment as explained in the graphic below.

The recommended way to clean an application is to:

Step Action
1

Move all the elements you want to delete to a specific space.

When selecting elements to delete from the application, make sure there are no dependencies left between the elements you want to delete and the elements you want to keep on the deployment. Otherwise, the application re-import will not be successful.
2

When all the elements you want to delete are in the same space, on the main menu, click the Configuration   icon. On the left menu, click Spaces in the Administration section.
3

Select the space that you want to delete on re-import, then select the Hide space and content check box.
4

Dashboards behave like spaces. Hide the dashboards you want to delete. 
5 Export your entire application contents.
6 If you choose to create a new version, the date must be after the current version start, but not in the future. You can also choose to overwrite the current version. Click the Continue button.
7

Re-import your application into the target node. On the main menu, click the  Configuration    icon. On the left menu, click  Application in the Administration section.

 Click the Import button. The checkboxes corresponding to the hidden spaces of the file are cleared by default. Leave them as is.
8

Click the Continue button. Your deployment is updated to contain only your definitive data. An intermediary screen lists the elements (with type) that will be deleted, as well as the user instances that will be deleted or ignored.

In the table displaying the ignored user instances, you can choose if you want to delete some of those instances as well or to keep them in your current application.
9 Click the Continue button. The data that was unselected during the import is deleted from the deployment.
10

If an error message is displayed following the import, start again from your last checkpoint. For more information, see Checkpoint.
Once your deployment is updated, the deleted spaces and elements are deleted only starting from the import date you selected.  When you navigate farther back in time, you will still be able to see the deleted elements. However, you will not be able to rollback the deployment to that previous state. 

You can export an application from the user interface, the shell or via JMX.

Purge, users and roles are not linked to a version because these elements do not change through time. As a consequence, when you export a previous version, you will always get the latest value for these elements.

Please note that space related values (such as manual constants or calendar configuration) can be modified over intervals that overlap several versions, and thus alter previous versions export.
To avoid that, please use the FROM_VERSION_START constant in data integration mappings. For more information, see Configure mappings: Special values.

Export an application from the user interface (UI)

To export an application from the UI, follow these steps.

Step Action
1

From the source deployment, on the main menu, click the  Configuration    icon. On the left menu, click Application in the Administration section.
2

Click the Export Button for the current application version or the Export link of any past version.
3

Click the Export button.


If you have a Space from which to export properties area and you select spaces in this area, a data integration properties export file will also be generated and you may be asked for a password. For more information, see Importing and exporting data integration properties.
4

Click the Download application here hyperlink and save the .appx file onto your computer.

Export an application from the shell

To export an application from the shell, use the exportApplication command. The syntax is:

exportApplication <output file path> <application version uuid> [<space name> <space name>]

Examples

  • Export full HVP application:
g! exportApplication "C:\backup\hvp.appx" "00000000-f35c-0000-160a-1ade8f902001"
Application 'HVP for Operational Supervisor (Intraday)' successfully exported into 'C:\backup\hvp.appx'
  • Export only a subset of HVP:
g! exportApplication "C:\backup\hvp.appx" "00000000-f35c-0000-160a-1ade8f902001" hvp hvpConfiguration hvpClassifier "hvp analysis"
Application 'HVP for Operational Supervisor (Intraday)' successfully exported into 'C:\backup\hvp.appx'

listApplicationVersions

To get the UUID of the application version you want to export, use the listApplicationVersions command. The syntax is:

g! listApplicationVersions
Application Versions: 
- <version UUID> started at <version valid time start> : <version description>
g! listApplicationVersions
Application Versions: 
- 00000000-f35c-0000-160a-1ade8f902001 started at 2017-12-21T00:00:00.000+02:00 : Taken Public Holidays into account for Baseline computings

listApplicationSpaces

 To list the spaces of an application, use the listApplicationSpaces command. The syntax is:

g! listApplicationSpaces
Spaces of <application name>:
- <space name> [: <space label>]
- <space name> [: <space label>]
...

Example:

g! listApplicationSpaces
Spaces of HVP for Operational Supervisor (Intraday): 
- hvp
- hvp analysis
- hvpClassifier
- hvpConfiguration
- decd55b5-5032-457d-88c4-fb5c7899c15f : PILING UP
- 5a3c3ae2-1019-4e0f-853a-b41c41149424 : HOME
- 39314efb-2d87-4787-b9fc-fca070bc7462 : MINI DASHBOARD
- 66425505-e2ce-448f-8ef7-67ba3e616448 : LOST & STUCK
- 0ee52d07-deaf-45ac-b43f-b3a9516e7bf4 : LOW RATE
...

Export an application via JMX

  1. Use a JMX client such as jconsole and connect to the application.
  2. In the MBeans tree, open the node com.systar.carbon.application.impl.importexport.ImportExportCommandsMXBean

  3. You can then invoke the following operations:
    • listApplicationVersions
    • listApplicationSpaces
    • exportApplication

Each operation is self-documented in JMX.

Import an application

Security best practices
You must never upload untrusted files to your installation. Make sure to have every file scanned by an anti-malware software before it can be used in the product.

Select the application version

When you import an application, you are asked to choose between overwriting the current application version or creating a new version. The resulting version becomes the version in which the imported elements on your deployment become valid. For more information about versions, see Application version in the Glossary. 


We saw earlier that export files can be either full or partial. Relative to the type of the imported file, the import process behaves differently:

Select the import type

When importing the same application: 

  • With a full export file – the hidden spaces in the export file are deselected by default, which means you do not have to import them unless you want to. All unselected spaces (hidden or not) and their contents are deleted from the node on import. 
  • With a partial export file – for example, you are exporting routes from another application. All space present in the appx file are selected by default. if you deselect a space, its content will be ignored on import.

Important: For clustered deployments, if the application you want to import is not the node application, whatever the type of the export file, a warning informs you that the content of the imported application will be merged with the content of the node application.  All unselected spaces (hidden or not) and their contents are ignored during import. 

Tip

When you're on the Import application screen, the hidden spaces or dashboards are represented as slightly greyed out:

Import an application from the UI

From the UI of Axway Decision Insight, you can import an application, data integration properties or both. To import data integration properties, see Importing and exporting data integration properties.

To import an application from the UI, follow these steps.

Step Action
1

From the source deployment, on the main menu, click the  Configuration icon. On the left menu, click  Application in the Administration section.
2

Click the Import button.
3

Under Application file, click the Select link and browse for an .appx file.
4 Click Next.
5 In the Configuration screen, specify the creation date for a new version that will contain your imported files or overwrite the current application version if an application already exists.

  • First-time import on a deployment – Select the furthest date in time where you have data to monitor.

  • Update an existing application – The new version start date must be after the current version start date, but cannot be set in the future. The latest version can also be overwritten.
6 In the Content screen:
When importing the same application When importing another application
  • If you're doing a full re-import: unselect the spaces you want to delete.
  • If you're doing a partial import, for example, you are adding a new route or mapping, unselect the spaces you don't need to import.
 Unselect the spaces you don't want to merge
7 Click the Import button.

Import an application via automatic provisioning

To import an application via automatic provisioning,  copy the import file into the <installation directory>/ var/data/carbon-provisioning/autoimport/incoming directory of your standalone node or of your primary node.

The application is imported by overwriting the current application version.

When you import an application on a node that contains no application yet, an initial application version is created at the valid time field specified in the .appx file. To modify the date at which the initial version is created, add a .properties file in the same location as the import file.

Hidden spaces

When an application is imported using automatic provisioning, the hidden spaces specified in the file:

  • In the case of full import, are deleted together with all their content.
  • In the case of partial import, are ignored.

Application merge

If the imported application is not the node application, no merge is performed, the import is rejected

The node regularly scans this directory and automatically imports all files with an .appx extension.

  • If the file can be imported as an application, the application is imported and the file is moved to the done subdirectory (the file name is prefixed with the import date).
  • If an error occurs during the application import, the file is moved to the error subdirectory (the file name is prefixed with the import date).

A temporary file (named after the file but with the .tmp extension) is created at the beginning of an import process and deleted just after the import has completed.

For more information, see Automatic process.

Import an application from the shell

To import an application from the shell, use the importApplication command. The syntax is:

importApplication <input file path> <import date> [<allow application merge> <space name> <space name>]

A new application version will be created at the import date. The import date must be after the current version start and cannot be set in the future. To overwrite the current application version, FROM_VERSION_START should be used as the import date.

On full import:

  • If no space name is specified, then all hidden spaces from the import file are deleted.
  • If only a subset of application spaces is specified, then all the other spaces are deleted. 

On partial import:

  • If no space name is specified, then all spaces are updated.
  • If only a subset of application spaces is specified, then only the specified spaces are updated.

Examples

  • Import HVP application, valid from January 1st, 2018
g! importApplication "C:\backup\hvp.appx" 2018-01-01T00:00:00
Application file 'hvp.appx' successfully imported into the platform
  • Import only a subset of the HVP application, from today
g! importApplication "C:\backup\hvp.appx" today true hvpConfiguration hvpClassifier "hvp analysis"
Application file 'hvp.appx' successfully imported into the platform

If the imported application is not the node application, a merge is only performed if the <allow application merge> parameter is set to true. Otherwise, the import is rejected

Import an application via JMX

  1. Use a JMX client such as jconsole and connect to the application
  2. In the MBeans tree, open the node com.systar.carbon.application.impl.importexport.ImportExportCommandsMXBean

You can then invoke the operation importApplication.  The operation is self-documented in JMX.

Whatever the value of the mergeApplication parameter, if the imported application is the same as the application node:

On import of a full export:

  • If no space name is specified, then all hidden spaces from the import file are deleted.
  • If only a subset of application spaces is specified, then all the other spaces are deleted. 

On import of a partial export:

  • If no space name is specified, then all spaces are updated.
  • If only a subset of application spaces is specified, then only the specified spaces are updated.

If you try to import a different application, if the mergeApplication parameter is false, the import is rejected, if true the imported application content is merged into the node application.



Related Links