API data migration from Enterprise 10 to Enterprise 11 Control Room

As a Control Room administrator with View and Manage Migration role permissions, use the Migration APIs to migrate data from Enterprise 10 to the latest Enterprise 11 Enterprise Control Room.

The Migration APIs allow you to,

  1. Save / update connection configuration to the 10.x Control Room database
  2. Save / update connection configuration to the 2.x Bot Insight database, if available
  3. Specify option to migrate data based on Roles, Users or Bots
  4. Fetch list of data based on option specified for migration that is, Roles, Users, or Bots
  5. View the migration progress summary
  6. View migration statistics of number of entities that succeeded / failed per migration
  7. Fetch list of new and updated bots from 10.x Control Room post migration
  8. Migrate files in bulk from the 10.x Control Room My docs folder post migration

Alternately, you can use the Migration wizard given in Administration > Migration module to migrate the data from the Control Room user interface. Refer Migration Overview for details.

Note: The examples provided in this article are for reference only.

API End Point

Use the following end points to access the API:

  1. For migration process use <Control Room URL>/v2/migration
  2. For migrating files from the My Docs folder of source 10.x Control Room after the migration process has completed use <Control Room URL>/v1/migration

For example,

https://crdevenv.com:81/v2/migration

Migration Process APIs

The Migration APIs allow you to migrate 10.x Control Room data to 11.x Control Room using the end point mentioned earlier.

Before accessing the Migration API's you must first use the authentication API and pass it as a token to use a particular Migration API.

  1. Use the POST method to generate a token using the end point http(s)://<hostname:port>/v1/authentication. For this provide the Control Room instance as Server Name /Hostname /IP and the Port number.

    For example,https://crdevenv.com:81/v1/authentication

  2. Provide the following request payload in Headers

    "X-Authorization" : "Authorization token"

    "Content-Type" : "application/json"

  3. Provide the following request payload in Body:

    {

    "username": "<Username>",

    "password": "<Password>"

    }

    For example,

    {

    "usename": "Ellie.Brown",

    "password": "12345678"

    }

1. Connect to source Control Room database

This API allows you to save and update the connection configuration to the source 10.x Control Room database.

  1. Provide the "X-Authorization" and "Content Type" parameters in Headers.
  2. Provide credential parameters in Body
  3. Use the POST method to connect to the 10.x Control Room database using the end point http(s)://<hostname:port>/v2/migration/connection

    For example,https://crdevenv.com:81/v2/migration/connection

  4. Provide the following request parameters in Body:

    {

    "host": "string", "port": 0, "databaseName": "string", "username": "string", "password": "string", "integratedSecurity": true, "encrypt": true, "privateKey": "string", "repoPath": "string"

    }

    For example,

    {

    "host": "PRODUCTLT",

    "port": 1433,

    "databaseName": "CR104MIG",

    "username": "Ellie.Brown",

    "password": "12345678",

    "integratedSecurity": true,

    "encrypt": true,

    "privateKey": "ABC123",

    "repoPath": "D:\\Data\Automation Anywhere Server Files"

    }

  5. Click Send.

Parameter Description

Parameter Description
host Source Control Room database host name
port Source Control Room database port number
databaseName Source Control Room database name
username Username to connect to database
password Password to connect to database
integratedSecurity An indicator whether to use Windows authentication when connecting to source database. Set this to true if you want use Windows authentication. The default value is false
encrypt An indicator whether to use secure connection to source database. Set this to true if you want to use a secure connection. The default value is false
privateKey The private key to decrypt credential values in source database. This is available for configuration during the initial Control Room setup.
repoPath The shared repository path where Control Room 10.x repository is stored

2. Get stored connection details

This API allows you to fetch the stored connection details of source 10.x Control Room database from where the data can be migrated.

  1. Provide the "X-Authorization" and "Content Type" parameters in Headers.
  2. Provide credential parameters in Body
  3. Use the GET method to fetch the connection configuration of 10.x Control Room database using the end point http(s)://<hostname:port>/v2/migration/connection

    For example, https://crdevenv.com:81/v2/migration/connection

  4. Click Send
  5. You can view the result in Body data:

    {

    "host": "productlt",

    "port": 1433,

    "databaseName": "CR104MIG",

    "username": "",

    "password": "",

    "integratedSecurity": true,

    "encrypt": false,

    "privateKey": "",

    "repoPath": "D:\\DATA\AUTOMATION ANYWHERE SERVER FILES"

    }

Parameter Description

Parameter Description
host Source database host
port Source database port
databaseName Source database name
username Username to connect to source database
password Password to connect to source database
integratedSecurity An indicator whether to use Windows authentication when connecting to source database, default value is false
encrypt An indicator whether to use secure connection to source database, default value is false
privateKey Private key to decrypt credential values in source database
repoPath The shared repository path where Control Room 10.x repository is stored

3. Connect to 2.x Bot Insight database, if available

This API allows you to connect to the source 2.x Bot Insight database if available, to migrate analytics data.

  1. Provide the "X-Authorization" and "Content Type" parameters in Headers.
  2. Provide credential parameters in Body.
  3. Use the POST method to connect to the Bot Insight database using the end point http(s)://<hostname:port>/v2/migration/connection /botinsight

    For example, https://crdevenv.com:81/v2/migration/connection/botinsight

  4. Provide following request parameters in Body:

    {

    "host": "string",

    "port": 0,

    "databaseName": "string",

    "username": "string",

    "password": "string",

    "integratedSecurity": true,

    "encrypt": true,

    "serverUrl": "string"

    }

    For example,

    {

    "host": "Productlt",

    "port": 8091,

    "databaseName": "BotInsight",

    "username": "Ellie.Brown",

    "password": "12345678",

    "integratedSecurity": true,

    "encrypt": true,

    "serverUrl": "https://productlt.example.com:82/analytics"

    }

  5. Click Send
  6. The connection parameters are successfully saved when the response status is 200 Successful operation .

Parameter Description

Parameter Description
host Source Bot Insight database host name
port Source Bot Insight database port number
databaseName Source Bot Insight database name
username Username to connect to database
password Password to connect to database
integratedSecurity An indicator whether to use Windows authentication when connecting to source database. Set this to true if you want use Windows authentication. The default value is false
encrypt An indicator whether to use secure connection to source database. Set this to true if you want to use a secure connection. The default value is false
serverUrl Server url where the Bot Insight Visualization ServerPort

4. Get stored connection details

This API allows you to fetch the stored connection details of source 2.x Bot Insight database from where the data can be migrated.

  1. Provide the "X-Authorization" and "Content Type" parameters in Headers.
  2. Provide credential parameters in Body
  3. Use the GET method to fetch the connection configuration of 10.x Control Room database using the end point http(s)://<hostname:port>/v2/migration/connection/botinsight

    For example,https://crdevenv.com:81/v2/migration/connection/botinsight

  4. Click Send
  5. The connection parameters are successfully saved when the response status is 200 Migration config .
  6. You can view the result in Body data:

    {

    "host": "Productlt",

    "port": 8091,

    "databaseName": "BotInsight",

    "username": "Ellie.Brown",

    "password": "12345678",

    "integratedSecurity": true,

    "encrypt": true,

    "serverUrl": "https://productlt.example.com:82/analytics"

    }

Parameter description

Parameter Description
host Source Bot Insight database host name
port Source Bot Insight database port number
databaseName Source Bot Insight database name
username Username to connect to database
password Password to connect to database
integratedSecurity An indicator whether to use Windows authentication when connecting to source database. Set this to true if you want use Windows authentication. The default value is false
encrypt An indicator whether to use secure connection to source database. Set this to true if you want to use a secure connection. The default value is false
serverUrl Server url where the Bot Insight Visualization ServerPort

5. List of entities of TYPE available for migration in source database

This API returns list of entities available for migration in source database by TYPE parameter. Using the either of the options - Role, User, Bot, or Schedule, you can migrate all data that is associated with the parameter chosen.

  1. Provide the "X-Authorization" parameters in Headers.
  2. Use the GET method to connect to the Control Room database using the end point http(s)://<hostname:port>/v2/migration/connection /entities followed by TYPE parameter that could include any one of the option - Roles, Users, Bots, or Schedules

    For example,https://crdevenv.com:81/v2/migration/connection/entities?Type=ROLE

  3. Click Send
  4. The data is returned when the response status is 200
  5. The list of entities based on TYPE parameter are displayed in Body.

    {

    "entities":

    [

    { "id": "0", "type": "ROLE", "sourceId": "1", "targetId": "0", "name": "Admin", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "2", "targetId": "0", "name": "Basic", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "3", "targetId": "0", "name": "IQBotValidator", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "4", "targetId": "0", "name": "AnalyticsExperts", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "5", "targetId": "0", "name": "AnalyticsConsumers", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "6", "targetId": "0", "name": "BotAgentUser", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "7", "targetId": "0", "name": "BotFarmAdmin", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "8", "targetId": "0", "name": "IQBotServices", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "9", "targetId": "0", "name": "Bot Creator 10x", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "10", "targetId": "0", "name": "Bot Runner 10x", "status": "SUCCESS", "reason": "" },

    { "id": "0", "type": "ROLE", "sourceId": "11", "targetId": "0", "name": "Bot Scheduler 10x", "status": "SUCCESS", "reason": "" }

    ]

    }

Parameter description

Parameter Description
id Migration ID
type Type of entity selected for migration - Role, User or Bot
sourceId Id of entity in the source database
targetId Id of entity after Migration in the target database
name Name of the entity in the source database
status The migration status for that particular entity
reason The reason for migration failure for that particular entity

6. Prepare migration data based on User input

This API allows you to migrate entities with associated data based on the sub-section of the entity type specified for migration.

  1. Provide the "X-Authorization" and "Content Type" parameters in Headers.
  2. Use the POST method to migrate the data using the endpoint http(s)://<hostname:port>/v2/migration/prepare

    For example,https://crdevenv.com:81/v2/migration/prepare

  3. Provide following request payload in Body:

    {

    "selected":

    [

    { "type": "<enitity type>",

    "sourceId": "string" }

    ],

    "excludes": [ "<entity type>"

    ]

    }

    For example,

    { "selected": [ { "type": "ROLE", "sourceId": "12" } ], "excludes": [ "BOT" ] }

  4. Click Send
  5. The data is listed successfully for migration when the response status is 200
  6. The result is displayed in the Body

    { "selected":

    [

    { "type": "ROLE", "sourceId": "12" } ],

    "excludes": [ "BOT" ]

    }

Parameter description

Parameter Description
type Type of entity selected for migration - Role, User or Bot and Schedules
sourceId The id of the entity in the source database
excludes

The entity name that is excluded from migration. The options are available based on the entity type selected.

When you select Role or User, you can Exclude Bots and Schedules. When you select Bots and Schedules, you can Exclude MetaBots), or Overwrite existing Bots.

7. Start Migration

This API allows you to launch the migration process.

  1. Provide the "X-Authorization" parameters in Headers.
  2. Use the POST method to migrate the data using the endpoint http(s)://<hostname:port>/v2/migration/start/async

    For example, https://crdevenv.com:81/v2/migration/start/async

  3. Click Send
  4. The data migration starts successfully when the response status is 200 Successful operation
  5. The result is displayed in the Body data

    {

    "id": 1,

    "name": "2018.07.17.16.13.48.ellie.brown",

    "createdBy": 1,

    "migrationType": "ROLE_EXCLUDE_BOT_SCHEDULE"

    }

Parameter description

Parameter Description
id Migration ID
name Name of the user who initiated the migration
createdBy Id of the entity that started the migration. For example, the Control Room administrator
migrationType The migration type chosen - Role, User, or Bots and Schedules

8. Migration object by id

This API lists the migration object details based on the ID that is generated using the Start Migration API.

  1. Provide the "X-Authorization" parameters in Headers.
  2. Use the GET method to fetch object details by id using the endpoint http(s)://<hostname:port>/v2/migration/<id>

    For example, https://crdevenv.com:81/v2/migration/9

  3. Click Send.
  4. The object details are listed successfully when the response status is 200
  5. The details are shown in the Body data:

    {

    "id": "9",

    "name": "2018.07.17.16.13.48.ellie.brown",

    "startTime": "2018-07-17T10:43:48.127Z",

    "endTime": "2018-07-17T10:43:49.833Z",

    "createdBy": "1",

    "migrationType": "ROLE_EXCLUDE_BOT_SCHEDULE",

    "entities": []

    }

Parameter description

Parameter Description
id Migration ID
name Name of the user who initiated the migration
startTime The time when the migration was initiated
endTime The time when the migration was complete
createdBy Id of the entity that started the migration. For example, the Control Room administrator
entities List of entities migrated during migration process
migrationType The migration type chosen - Role, User, or Bots and Schedules

9. Migration Progress

This API allows you to view the process of migration that is in progress.

  1. Provide the "X-Authorization" and "Content Type" parameters in Headers.
  2. Provide credential parameters in Body
  3. Use the GET method to fetch object details by id using the endpoint http(s)://<hostname:port>/v2/migration/pogress

    For example, https://crdevenv.com:81/v2/migration/progress

  4. Click Send.
  5. The object details are listed successfully when the response status is 200
  6. The details are shown in the Body data:

    {

    "migration":

    { "id": "10", "name": "2018.07.17.16.55.59.ellie.brown", "startTime": "2018-07-17T11:25:59.800Z", "endTime": "2018-07-17T11:26:16.002Z", "createdBy": "1", "migrationType": "BOT_EXCLUDE_MetaBot", "entities": [] },

    "current": "SCHEDULE",

    "progress":

    {

    "BOT": { "total": "10", "successful": "7", "failed": "0", "skipped": "3" },

    "SCHEDULE": { "total": "8", "successful": "8", "failed": "0", "skipped": "0" }

    }

    }

Parameter description

Parameter Description
id Migration id
name Migration name displayed
startTime Timestamp when Migration process started
endTime Timestamp when Migration process completed. Null when migration is in progress
createdBy Id of the user who created/started the migration process
current Type of entity currently being migrated - ROLE, USER, CREDENTIAL, BOT, or SCHEDULE ]
progress

Progress of the entities -

  • total - total number of entities of specific type to be migrated
  • successful - number of entities out of total migrated successfully
  • failed - number of entities out of total failed to be migrated
  • skipped - number of entities out of total skipped during migration

10. Migration statistics - number of entities that succeeded / failed per migration

This API allows you to view the number of successful or failed entities per migration.

  1. Provide the "X-Authorization" parameters in Headers.
  2. Use the GET method to fetch object details by id using the endpoint http(s)://<hostname:port>/v2/migration/statistics

    For example, https://crdevenv.com:81/v2/migration/statistics

  3. Click Send.
  4. The object details are listed successfully when the response status is 200
  5. The details are shown in the Body data:

    {

    "items": [

    { "id": "1", "name": "2018.07.13.11.14.59.ellie.brown", "startTime": "2018-07-13T05:44:59.787Z", "endTime": "2018-07-13T06:56:25.537Z", "createdBy": "1", "duration": "4285s", "numSuccess": 0, "numFailed": 0, "numSkipped": 0 },

    { "id": "2", "name": "2018.07.13.12.28.08.ellie.brown", "startTime": "2018-07-13T06:58:09.283Z", "endTime": "2018-07-13T06:58:12.910Z", "createdBy": "1", "duration": "3s", "numSuccess": 1, "numFailed": 1, "numSkipped": 0 },

    { "id": "3", "name": "2018.07.13.12.40.34.ellie.brown", "startTime": "2018-07-13T07:10:34.470Z", "endTime": "2018-07-13T07:10:40.060Z", "createdBy": "1", "duration": "5s", "numSuccess": 10, "numFailed": 0, "numSkipped": 0 },

    { "id": "4", "name": "2018.07.13.12.42.19.ellie.brown", "startTime": "2018-07-13T07:12:20.007Z", "endTime": "2018-07-13T07:12:23.107Z", "createdBy": "1", "duration": "3s", "numSuccess": 0, "numFailed": 0, "numSkipped": 6 },

    { "id": "5", "name": "2018.07.13.13.39.53.ellie.brown", "startTime": "2018-07-13T08:09:53.113Z", "endTime": "2018-07-13T08:10:02.673Z", "createdBy": "1", "duration": "9s", "numSuccess": 4, "numFailed": 0, "numSkipped": 0 }

    ]

    }

Parameter description

Parameter Description
id migration id
name Migration name displayed
startTime Timestamp when Migration process started
endTime Timestamp when Migration process completed. Null when migration is in progress
createdBy Id of the user who created the object
duration Duration of migration - seconds or nano seconds
numSuccess Number of items successfully migrated
numFailed Number of items that failed to migrate
numSkipped Number of items that were skipped during migration

Post Migration process APIs

Use the Migration APIs after the process has completed to

  1. Import files from the My Docs folder of 10.x Control Room
  2. Fetch the list of new or modified bots from 10.x Control Room since last migration run
    Note: Before accessing the APIs you must first use the authentication API and pass it as a token to use a particular Migration API.
  3. Use the POST method to generate a token using the end point http(s)://<hostname:port>/v1/authentication. For this provide the Control Room instance as Server Name /Hostname /IP and the Port number.

    For example,https://crdevenv.com:81/v1/authentication

  4. Provide the following request payload in Headers

    "X-Authorization" : "Authorization token"

    "Content-Type" : "application/json"

  5. Provide the following request payload in Body:

    {

    "username": "<Username>",

    "password": "<Password>"

    }

For example,

{

"usename": "Ellie.Brown",

"password": "12345678"

}

Important: When the error code 404 is shown while using any or all the post migration APIs, re-use the API to fetch the list of root folders from 10.x Control Room i.e. http(s)://<hostname:port>/v1/migration/legacyrepository/rootDirectories.