Model Management Server Import Utility

Table of Contents

• Overview
• Import Modes
• Limitations
• Supported Platforms
• Command-Line Options
• Import Utility Output
• Additional Files
• Supported AMS Resources
• Deployment
• Commit Translation

Overview

The TIBCO Streaming Model Management Server (MMS) Import Utility is used for importing assets from the Artifact Management Server (AMS) into the MMS. The features of this utility are:

• Import all projects along with their history.
• Import all eligible deployment descriptors.
• Import all users and roles into a file.

Note

• Only APPROVED commits are imported.
• It is preferred that users should do an initial migration from AMS to MMS for testing purposes. If satisfied, they can proceed with the final migration.
• OIDC is not supported for the AMS side of the migration. The workaround is to add a local authentication realm in the AMS config to enable an admin with basic authentication to perform the migration.

Supported Platforms

For more information on the platforms supported by the MMS Import Utility, see Supported Platforms.

Command Line Options

The MMS Import Utility supports the following common options across all commands:

• -h, --help - Shows help message
• -V, --version - Shows version information

The MMS Import Utility supports the following ‘import commands’:

• Common options for all ‘import commands’
  • -l, --ams-url - The API base URL for AMS (required)
  • -u, --ams-user - The username to connect to AMS
  • -p, --ams-password - The password to connect to AMS. The password can be read from stdin
  • -t, --ams-token - The token to connect to AMS
  • -f, --ams-project-filter - The filter to use to choose AMS projects to import (optional, If not specified all AMS projects are imported)
  • -L, --url - The API base URL for MMS (required)
  • -U, --user - The username to connect to MMS
  • -P, --password - The password to connect to MMS. The password can be read from stdin
  • -T, --token - The token to connect to MMS
  • -s, --space-name - The name of the space in which to import all projects (optional if MMS has a single accessible and update-able space)
  • -g, --group-identifier - The group identifier to use for all imported AMS projects (required)
  • -i, --artifact-identifier-prefix - An optional prefix to use for non-compliant artifactId (generated from the project name) (optional, defaults to ams-)
  • -d, --default-streaming-cluster - The name of the default MMS streaming cluster (optional if MMS has discovered a single streaming cluster)
  • --dry-run - A flag to trigger a dry run (optional, defaults to false)
  • -M, --deployment-mapping - The file that contains the mapping AMS deployment descriptors to MMS streaming clusters (optional if MMS has discovered a single streaming cluster)
  • -R, --report-file-path - The file to write the import report to (optional defaults to import-<timestamp>.txt in current working directory)
  • -W, --password-file-path - The file to write the exported passwords to (optional defaults to passwords-<timestamp>.txt in current working directory)
  • -B, --permission-bindings-file-path - The file to write the exported permission bindings to (optional defaults to permission-bindings-<timestamp>.txt in current working directory)
  • -c, --retain-commits - The number of latest commits to retain during import (required)
    • -1 to import and retain all commits
    • 0 to import but squash all commits
    • n where n is a positive number indicating the number of commits to retain
  • -v, --verbose - Decides the verbosity of the import logs
    • 1 - set logging to DEBUG level
    • 2 - set logging to TRACE level
  • -o, --timeout-seconds - Sets the timeout in seconds for checkpoint creation, publishing operations
• Import Commands
  • import-by-projects - Triggers ‘Import by Projects’ mode and supports the following options
    • -D, --primary-target-decision-policy - An optional policy to decide how the primary deployment target is chosen (optional, defaults to by-count)
      • by-count - Chooses the most commonly used target
      • by-modified-date - Chooses the most recently updated target
      • ignore - Ignores targets completely
    • -S, --secondary-target-creation-policy - An optional policy to decide how the secondary deployment targets will be processed (optional, defaults to ignore)
      • dependents - Create a project per target dependent on the primary imported project
      • ignore - Ignores all targets
  • import-by-deployments - Triggers ‘Import by Deployments’ mode
• Browse Commands
  • browse-mms - Browses MMS and prints succinct information of the artifacts as a tree to the console.
    • -L, --url - The API base URL for MMS (required)
    • -U, --user - The username to connect to MMS
    • -P, --password - The password to connect to MMS. The password can be read from stdin
    • -T, --token - The token to connect to MMS
    • -F, --content-filter - A multi value option of artifact names/regexs whose contents should be printed to the console.
  • browse-ams - Browses AMS and prints succinct information of the artifacts as a tree to the console.
    • -l, --ams-url - The API base URL for AMS (required)
    • -u, --ams-user - The username to connect to AMS
    • -p, --ams-password - The password to connect to AMS. The password can be read from stdin
    • -t, --ams-token - The token to connect to AMS
    • -f, --ams-project-filter - The filter to use to choose AMS projects to browse (optional, If not specified all AMS projects are browsed)

NOTE The user needs to provide either -u, --ams-user and -p, --ams-password or -t, --ams-token to connect to AMS.

NOTE The user needs to provide either -U, --user and -P, --password or -T, --token to connect to MMS.

Import Utility Output

Additional Files

The following files are added to the imported MMS project:

Supported AMS Resources

The following tables give the details of the translation of AMS resources to MMS resources.

$ams-user: <hashed-password>,$ams-role

 {
  "@class": "com.tibco.ep.ams.model.response.RoleRecord",
  "name": "AMSAdmin",
  "users": [
    "admin",
    "test"
  ],
  "permissions": [
    "*"
  ],
  "entityId": "f67bc01de8864f349d8d8d524d628f53"
},
{
  "@class": "com.tibco.ep.ams.model.response.RoleRecord",
  "name": "AMSGuest",
  "users": [
    "guest"
  ],
  "permissions": [
    "project:read",
    "artifact:read",
    "group:read"
  ],
  "entityId": "1b36ad3ad7004e8cb71f5c5fb08d2b66"
}

{
  "bindings" : {
    "AMSAdmin" : [ "create", "read", "update", "delete", "approval", "deploy", "change permissions" ],
    "AMSGuest" : [ "read" ]
  }
}

# A mapping between AMS STREAMBASE_URI streamBase target and MMS streaming cluster name
sb://localhost:10000=foo.bar.streaming.cluster

# A mapping between AMS STREAMBASE_SERVICE_NAME streamBase target and MMS streaming cluster name
some.service.name=someother.foo.bar.streaming.cluster

# A mapping between AMS STREAMBASE_SERVICE_ADDRESS streamBase target and MMS streaming cluster name
some.service.address=another.foo.bar.streaming.cluster

Commit Translation

The utility can control how commits are imported in MMS from AMS using retain-commits.

Each commit in AMS is imported as a published checkpoint in MMS.

If retain-commits is -1, then all commits in AMS are individually imported into MMS as checkpoints/dependencies.

If retain-commits is 0, then all commits in AMS are imported into MMS as a single squashed checkpoint/dependency.

If retain-commits is n, then the latest n commits from AMS are imported into MMS as individual checkpoints or dependencies. All older commits from AMS are squashed into MMS as a single checkpoint or dependency. If the AMS project has more than n commits, then the MMS project has n+1 commits. If the AMS project has less than or equal to n commits, then the MMS project has all the commits.