Export and import integrations and microapps 编辑

The Microapps service allows you an option to easily export and import integrations and microapps.

With export you can:

• Export an integration alone, with all microapps, or with selected microapps.
• Export microapps individually from an existing integration.

With import you can:

• Import an integration, with all microapps.
• Import microapps individually from an existing export file in addition to new versions of current microapps.

Benefits

Importing and exporting integrations and microapps can be used for the following scenarios:

• Backup and restore existing integrations and microapps.
• Reduce the time it takes to develop extra microapps with integrations.
• Test new configurations without affecting production integrations.
• Troubleshoot by allowing you to develop safe ways to test proposed solutions.
• Collaborate with other microapps developers within your organization or the broader Citrix Microapp Platform developer community.

Export Feature

The export feature packages the various settings and configurations into a file with a .mapp extension. This file can be imported into the Microapps admin console. There are two types of .mapp files. One for integrations and one for microapps.

Note

No sensitive data is contained in the export file including User IDs, passwords, OAUTH client IDs, and client secrets.

Template Integration .mapp configuration files contain the following:

• Synchronization schedule and configurations
• Tables
  • Edit Schema options
  • Attributes selected
  • Filters and filter queries
• Relationships
• Actions
• Configuration
  • Integration name
  • Connector parameters
    • Service URL
  • Service Authentication
    • User name
    • Password
  • User Authentication Method
  • Other parameters
  • On-premises Configuration
  • Logging

Note

Microapps are exported, but not with any subscribers previously configured. Subscribers must be reconfigured once the microapp is imported. For more information, see Assign subscribers.

HTTP Integration .mapp configuration files contain the following:

• Data Loading
  • Data endpoints (including chained child endpoints)
• Tables
• Relationships
• Service Actions
• Configuration
  • Integration name
  • Connector parameters
    • Base URL
  • Icon
  • On-premises instance
  • Service authentication
    • Authentication method
  • Service Action Authentication
    • Use Separate User Authentication in Actions
    • Authentication method
  • Logging

Microapp .mapp configuration files contain the following:

• Properties
  • Name
  • Description
  • Icon
  • Action
  • (Action page)
• Notifications
  • Name
    • Trigger
  • Toggles
  • Content
    • Action Buttons
  • Target Page
  • Settings
    • Conditions
  • Expiration conditions
• Pages
  • All Page properties and actions
  • All Page formatting
  • All page components and settings
  • All actions called
• Localization
  • All localization settings
• Metadata
  • Identification of the integration that was used to build your microapp.
  • A mapping structure of microapp components to the integration data cache layer must properly map to the new integration.
  • No subscriber settings are exported.

Export a Configuration

To export a configuration file, follow these steps:

1. Open the Microapps management console and locate the integration you want to export.
2. Click the ellipses menu for the integration and select Export integration.
3. Input the optional values for the Vendor and Description fields.
4. Select or deselect the microapps that you want to include in the export file.
5. Select Export.
6. Save the resulting .mapp file to a safe location. The .mapp configuration file for the integration is exported in the .mapp file format to your local machine.

Export a microapp

To export a microapp file, follow these steps:

1. Open the Microapps management console and locate the integration you want to export the microapp from.
2. Click the ellipses menu for the microapp you want to export and select Export.
3. Save the resulting .mapp file to a safe location. The .mapp configuration file for the integration is exported in the .mapp file format to your local machine.

Import feature

When importing you integration configurations and microapps consider the following before beginning your export/import workflow:

• What the state of the integration will be after importing.
• Depending on the type of integration exported and the settings that were configured, the integration configuration must be updated.
• After importing, the integration status can show a warning that Authentication configuration needed. You will need to configure authentication credentials again for the import to be successful.
• No Syncs, caching, or actions are possible until the Service credentials are updated.

OAuth

When exporting and importing integration and microapps that use OAuth, consider the following before beginning your export/import workflow:

• For integrations with OAuth configured for Service accounts or Service Actions, the integration is exported without client secrets.
• Doing so causes problems for any authentication schemes that use OAuth that can include the Service Authentication scheme and the Service Action Authentication scheme.
• No Syncs, or actions are possible until the Service credentials are updated.
• Reauthentication is required to obtain updated access tokens from the System of Record.

To fill in the OAUTH credentials, follow these steps:

1. From the Microapps admin console, locate the newly imported integration.
2. Click the ellipses menu for the integration and choose Edit.
3. Click Properties from the left
4. Fill in the missing passwords, secrets, and reauthenticate OAuth.

Importing microapps limitations

Microapps are created within integrations. The integration that is the parent to a microapp is called the source integration. When you import a microapp, you can import into the same source integration or another integration or target integration. There are significant limitations that must be understood when importing microapps into target integrations.

Known impacts of importing microapps:

• Any existing notifications (aka feed cards) are deleted when the original microapp is deleted.
• New feed cards and push notifications are generated starting with the next sync (full or incremental) of the new integration.
• Microapps can only be imported within a target integration that is the same integration type (Template or HTTP integration) as the source integration.

Note

Even if the underlying data structure (aka schema) is equal for the source and target integrations, the microapp import feature is unable to match the microapp data structure to a different type of integration.

The target integration has a matching database structure to the source integration:

• If there are some cached tables missing in the target integration (the schema is different), the microapp is imported as misconfigured.
• To prevent misconfiguration, make sure the schema of the source and target integrations are equal.
• Navigate through the integration schemas to verify the tables required by the microapp are included in the schema.

Microapp template schema

To view the schema of a template integration, follow these steps:

1. Log in to the Microapps admin console and locate the integration you want to view.
2. Click the ellipses menu and choose Edit.
3. Choose Tables from the left menu and click the button to edit schema.
4. Review the tables and compare the source and target schemas. This ensures that the identical tables and entities are being synced to the microapps data cache.

Microapp status after import

When microapps are imported, the following conditions occur:

• The microapp has no subscribers. Subscribers must be recreated manually.
• There will be no notifications created against this microapp until all subscribers are set and the next synchronization takes place.
• Notifications are generated automatically based on the notification trigger preferences (typically after the next synchronization).

Import Configuration Steps

To import a configuration, follow these steps:

1. Open the Microapps management console and click Add Integration at the top of the management console.
2. Select the type of integration you would like to add.
3. Select Continue button next to the option to Import a previously configured integration.
4. Drag your integration .mapp file or choose browse to select the file from a specific location.
5. If the wrong file was selected, you can choose to remove it by clicking the remove link. Otherwise, click Import.
6. The integration is displayed along side all the other integrations in the admin console.

Next steps:

• Add missing credentials to the new integration.
• Add subscribers to the new microapps.
• Delete the original integration on the target environment.

Import a microapp into an existing integration

Note

Microapps contain references to the data structure of the integration that was used to create them. Therefore, microapps must only be imported within a compatible target integration.

To import a new microapp into an existing target integration:

1. Open the Microapps admin console and locate the target integration.
2. Select the ellipses menu for the target integration and choose Import microapp.
3. Drag your integration .mapp file or choose browse to select the file from a specific location.
4. If the wrong file was selected, you can choose to remove it by clicking the remove link. Otherwise, click Import.
5. The microapp is displayed alongside all the other microapps for the integration.

Next steps:

• Add subscribers to the new microapps.

Import a new microapp version

You can update a microapp to a newer version from the microapp option (ellipsis) menu.

1. Select Import new version on your desired microapp in the Microapp Integration screen.

2. Drag your new microapp and select Import.

   (Optional) Select Delete existing feed cards if you want to completely remove the old version of your microapp from the system. If you do not select this option, your old microapp remains on the system marked with and end-of-life (EOL) flag. Your newer version is set as the active microapp. It is recommended you do not delete your old microapps to keep your created feed cards working correctly.

3. Click Import

Your new microapp is imported.

Next steps:

• Add subscribers to the new microapps.
• End of Life (EOL): You can set a microapp for end of life manually. The EOL toggle is found by clicking to edit the microapp and choosing Properties.

Upgrade an integration

To upgrade an integration, follow these steps:

1. Open the Microapps management console and click Upgrade integration at the top of the management console.
2. Select the type of integration you would like to add.
3. Drag your integration .mapp file or choose browse to select the file from a specific location.
4. If the wrong file was selected, you can choose to remove it by clicking the remove link. Otherwise, click Upgrade.
5. The integration is displayed along side all the other integrations in the admin console.

Upgrade integration considerations

• Only HTTP integrations are supported.
• Accepted data structures include new tables, new columns in existing tables, and new relationships. No modifications are allowed for:
  • Tables (removal of a table, or changing table names, primary keys).
  • Columns (removal of a column, or changing column names, data types, primary keys, unique constraint, nullable).
  • Relationships (no removal or change at all is possible).
• If parts of the old structure are no longer needed, you can keep the data structures empty, or use scripting to define values.
• No removal of target service actions is allowed. The validation applies to a service action universally unique identifier (UUID) and its definition, including parameters and so on.
  • If changes to service actions are required you must configure those service actions as new ones and update each microapp to call the updated service action.

When an integration upgrade succeeds, the following are fully replaced:

• All data end points and webhook definitions.
• Service actions (equal to keeping the old actions while adding the newly configured ones).
• All scripts prepared as part of HTTP integration scripting.

After upgrading:

• A full sync is required to cache the newly included tables and columns. Until successfully synced, the app may not work correctly (due to missing data).
• Only integration entities, relationships, data endpoints, scripts, and service actions are imported and available for the integration upgrade (no properties, authorization, and so on).