This transform tool is run for all migrations. The transform tool runs on any computer, including a partner's administrator laptop, and uses the Webex Public APIs. It reads the extract tool output ZIP (extracted_data_<timestamp>.zip) file as an input and transforms the raw XML into a JSON format that is used by the provisioning tool.
Prerequisites
After downloading and extracting the migration tools binaries, configure the following prerequisites:
- Set the REFRESH_TOKEN (Token copied from the Token Generator Tool) and NAME_OF_MAIN_LOCATION in the conf/partner.cfg file:
REFRESH_TOKEN=MzUwYjljODEtYmQ4MS00NGVhLTgwNGUtZjQ1NTEyZTViNzJkOTdjNAME_OF_MAIN_LOCATION=Main - Optionally set the PROVISIONING_ID (copied from the template in Partner Hub) in the conf/partner.cfg file:
PROVISIONING_ID=YmE4MjFkZGYtYTlkNy00NDdlLWIwODctYmNkOTM2NjUyYWQ1To get more complete verification of the customer email address you can optionally set the PROVISIONING_ID.
- Configure missing information in the input/customers.csv file (see next section) if missing.
- Add the end user email address in the input/users.csv file.
- If new phones are to be provisioned, add the mac address and email address of the user’s new phone to input/newphones.csv file. This is required only if the partner administrators want to provision new phones in Wholesale calling.
- Convert the BroadWorks Call Centers into the CxEssentials by using the input/cxessentials.csv file.
- Optionally, enable the UPGRADE_ALL_CALL_CENTERS_TO_CX_ESSENTIALS property to convert all Call Centers to CxEssentials.
- Use the input/locations.csv file to support the large enterprise migration that allows administrators to migrate their customer’s locations by location
- Optionally enable usage of MAC addresses from the User-Agent header of the SIP REGISTER message when the MAC address is not available in the Cisco BroadWorks device profile. Uncomment the line "USE_MAC_ADDRESS_FROM_SIP_REGISTER=yes" in file conf/partner.cfg
Filling-up the input/customers.csv
The file input/customers.csv provides data that maybe missing in Cisco BroadWorks or BroadCloud. This file can be left empty if all mandatory information is already available. You don’t have to fill in all columns, only the missing information is mandatory.
All these fields are optional.
The table below explains the most important columns in input/customers.csv.
| Column name | Rules |
|---|---|
| Id | In Cisco BroadWorks enterprise mode:
In BroadWorks service provider mode, this is the Cisco BroadWorks groupId. In BroadCloud, this is the Rialto customerId. |
| externalId | This is an identifier that matches the partner’s internal identifier for this customer. This column must be unique within a Webex partner org. This column is optional, a unique identifier will be generated automatically by the transform tool. This column is not used for groups within an enterprise. |
| customerName | For the enterprise, this column is used as the Webex customer name field. For a group within an enterprise, this column is used as the location name. Location names must be unique within an enterprise. |
| primaryEmail | This is used as the email address of the Webex customer admin. This column is optional for groups within an enterprise. |
| Address columns | For an enterprise, the address is used as the billing address and the first location address. For a group within an enterprise, the address is used as the location address. |
| timezone | Refer to the time zone section of this article. |
| language | See Languages Webex supports. |
| defaultvoicemailpin | See Set a voicemail PIN. |
Instructions to run
Run the Transform Tool in any operating system. Use the below steps to run the tool in Windows and macOS:
Windows
Execute the command below to run the Transform Tool in Windows:
transform.bat -extract=<Extract-Tool-Output-Zip-file> -customers=<Input-Path-Customers-CSV> -users=<Input-Path-Users-CSV> -newphones=<Input-Path-NewPhones-CSV>macOS
Execute the following steps to run the transform tool on macOS:
- Create a virtual environment and install dependencies to run the transform tool using Python:
python3 -m venv venvsource venv/bin/activatepython3 -m pip install requestspython3 -m pip install requests-oauthlib - Run the transform tool:
./transform.sh -extract=<Extract-Tool-Output-Zip-file> -customers=<Input-Path-Customers-CSV> -users=<Input-Path-Users-CSV> -newphones=<Input-Path-NewPhones-CSV>
Customer/user precheck
The Transform Tool makes API calls to Webex to catch potential provisioning issues. By default, it will validate the customer’s address and primary email. If the PROVISIONING_ID value is specified in the conf/partner.cfg file, it will also validate location information. The precheck results are included in the exception report.
Additionally, the following optional parameters can be added when running the transform tool:
precheck
In addition to running the precheck API for the customer information, the Transform Tool will also run the precheck API for the subscriber emails.
precheckinfo
By default, only precheck errors (i.e., issues that will block provisioning) are included in the exception report. Adding this flag will include successful precheck results as well (e.g., if a Webex organization already exists that can be automatically attached).
precheckinfo takes extra time to run.
Terminal logs
The following logs in the terminal on successful transform:
Summary ReportBroadWorks enterprises that can be successfully migrated: 1BroadWorks enterprises that cannot be migrated: 0BroadWorks users that can be successfully migrated: 4BroadWorks users that cannot be migrated: 0Phones that can be successfully migrated: 3Phones that are not compatible with Webex Calling: 0Exception report
Transform Tool generates the exception report inside the output/<timestamp>/exception_report.txt directory. You can use this report to identify the issues that will affect the migration and fix them in the Cisco BroadWorks system.
After modifying the user data to resolve the exception, rerun the Extract and Transform Tools with the new data. The sample exception report file as follows:
Exception ReportTue Oct 18 08:12:09 2022Enterprises with Communication Barring FeatureRecommendation: manually configure the Outgoing Calling Plan in Control Hub________________________________________________________________________________collabmigrationtestGRP_enggOutput
An output JSON (customer.json) file will be available in the output/<timestamp>/<groupid> directory. The sample customer.json file is as follows:
{ "customer": { "provisioningId": "!!!!!!!!!!REPLACE_WITH_PROVISIONINGID!!!!!!!!!!", "packages": [ "webex_calling", "common_area_calling" ], "externalId": "external_id_engg_grp1", "address": { "addressLine1": "100 Main Street", "addressLine2": "", "city": "Gaithersburg", "stateOrProvince": "MD", "zipOrPostalCode": "20877", "country": "US" }, "customerInfo": { "name": "Engineering Group - 1", "primaryEmail": "amareswaranvel+engineeringgroup1@gmail.com" }, "provisioningParameters": { "calling": { "location": { "name": "Main", "address": { "addressLine1": "100 Main Street", "addressLine2": "", "city": "Gaithersburg", "stateOrProvince": "MD", "zipOrPostalCode": "20877", "country": "US" }, "timezone": "America/New_York", "language": "en_us", "numbers": [ "+15205551101", "+15205551102", "+15205551103", "+15205551104", "+15205551105", "+15205551106", "+15205551107", "+15205551108", "+15205551109", "+15205551110" ], "mainNumber": "+15205551101" } } } }, "broadworks_info": { "service_provider_id": "collabmigrationtestSP_engg", "group_id": "collabmigrationtestGRP_engg" }, "subscribers": [ { "amareswaranvel+benjaminjack@gmail.com": { "subscriber": { "customerId": "!!!!!!!!!!REPLACE_WITH_CUSTOMERID!!!!!!!!!!", "email": "amareswaranvel+benjaminjack@gmail.com", "package": "webex_calling", "provisioningParameters": { "firstName": "Benjamin", "lastName": "Jack", "primaryPhoneNumber": "+15205551102", "extension": "1102" } }, "features": [ { "/v1/people/{personId}/features/voicemail": { "enabled": true, "sendBusyCalls": { "enabled": true, "greeting": "DEFAULT" }, "sendUnansweredCalls": { "enabled": true, "greeting": "DEFAULT", "numberOfRings": 3 }, "messageStorage": { "mwiEnabled": true, "storageType": "EXTERNAL", "externalEmail": "engineering17861@mailnator.com" } } } ], "devices": [ { "cisUuid": "!!!!!!!!!!REPLACE_WITH_PERSONID!!!!!!!!!!", "product": "DMS Cisco 7861", "mac": "CC98914EAAD7" } ] } }, { "amareswaranvel+lucasoliver@gmail.com": { "subscriber": { "customerId": "!!!!!!!!!!REPLACE_WITH_CUSTOMERID!!!!!!!!!!", "email": "amareswaranvel+lucasoliver@gmail.com", "package": "webex_calling", "provisioningParameters": { "firstName": "Lucas", "lastName": "Oliver", "primaryPhoneNumber": "+15205551103", "extension": "1103" } }, "features": [ { "/v1/people/{personId}/features/voicemail": { "enabled": true, "sendBusyCalls": { "enabled": true, "greeting": "DEFAULT" }, "sendUnansweredCalls": { "enabled": true, "greeting": "DEFAULT", "numberOfRings": 3 }, "messageStorage": { "mwiEnabled": true, "storageType": "EXTERNAL", "externalEmail": "engineering16821@mailnator.com" } } } ], "devices": [ { "cisUuid": "!!!!!!!!!!REPLACE_WITH_PERSONID!!!!!!!!!!", "product": "DMS Cisco 6821", "mac": "5486BCAE7E45" } ] } }, { "amareswaranvel+leojackson@gmail.com": { "subscriber": { "customerId": "!!!!!!!!!!REPLACE_WITH_CUSTOMERID!!!!!!!!!!", "email": "amareswaranvel+leojackson@gmail.com", "package": "webex_calling", "provisioningParameters": { "firstName": "Leo", "lastName": "Jackson", "primaryPhoneNumber": "+15205551104", "extension": "1104" } }, "features": [ { "/v1/people/{personId}/features/voicemail": { "enabled": true, "sendBusyCalls": { "enabled": true, "greeting": "DEFAULT" }, "sendUnansweredCalls": { "enabled": true, "greeting": "DEFAULT", "numberOfRings": 3 }, "messageStorage": { "mwiEnabled": true, "storageType": "EXTERNAL", "externalEmail": "engineeringmacpc@mailnator.com" } } } ], "devices": [] } }, { "amareswaranvel+owenalex@gmail.com": { "subscriber": { "customerId": "!!!!!!!!!!REPLACE_WITH_CUSTOMERID!!!!!!!!!!", "email": "amareswaranvel+owenalex@gmail.com", "package": "webex_calling", "provisioningParameters": { "firstName": "Owen", "lastName": "Alexander", "primaryPhoneNumber": "+15205551101", "extension": "1101" } }, "features": [ { "/v1/people/{personId}/features/voicemail": { "enabled": true, "sendBusyCalls": { "enabled": true, "greeting": "DEFAULT" }, "sendUnansweredCalls": { "enabled": true, "greeting": "DEFAULT", "numberOfRings": 3 }, "messageStorage": { "mwiEnabled": true, "storageType": "EXTERNAL", "externalEmail": "engineering8811@mailnator.com" } } } ], "devices": [ { "cisUuid": "!!!!!!!!!!REPLACE_WITH_PERSONID!!!!!!!!!!", "product": "DMS Cisco 8811", "mac": "F87B204E4066" } ] } } ], "auto_attendants": [], "call_queues": [], "hunt_groups": [], "schedules": [], "call_parks": [], "call_pickups": [], "paging_groups": [], "voice_portals": [ { "name": "Automated Voice Portal", "firstName": "Automated", "lastName": "Voice Portal", "languageCode": "en_us", "phoneNumber": "+15205551105", "extension": "1105" } ], "shared_call_appearances": [], "business_communicator_desktop_to_upgrade_to_webex_app": [ "PC Comm - Engg Device Profile" ], "connect_client_to_upgrade_to_webex_app": [], "locations": [],"webex_for_broadworks_info": { "users": [ { "id": "Y2lzY29zcGFyazovL3VzL1NVQlNDUklCRVIvY2QzNGViNWYtYTVmMi00OWQ1LTlkNWMtZTg1MDJiMDE4YTQ5" } ], "hydra_orgId": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi9jMjJiYTMwNC1mODQ4LTRlOTktYWFmYy0zYWRlMjBmYTgzZTg", "hydra_customer_config_id": "Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvYmIyMzA1MDEtMTUzMS00MzNiLTllM2QtODExY2FlYTExYmVk" }}The `webex_for_broadworks_info` JSON property is present for Webex for BroadWorks migrations only. The `broadcloud_info` JSON property is present for BroadCloud migrations only.
