Phonism-Webex by Cisco Integration Guide
To be moved to the Knowledge Base upon approval and release of the integration
Phonism-Webex by Cisco Integration Guide
- 1 Phonism-Webex by Cisco Integration Guide
1. Introduction
1.1 Purpose of the Integration
Phonism’s Webex by Cisco integration serves as a robust bridge between Phonism’s cloud-based device management and Webex by Cisco. Its primary objective is to assist Webex partners in the ability to deploy, manage, secure, and migrate VoIP devices at scale.
Security-compliant 3rd Party SIP Devices (Phones, ATAs, and Gateways) allow Webex customers and partners to have a flexible device management strategy where they can support Cisco devices with a fully managed Cisco-on-Cisco experience with deep Webex integration, as well as a self-managed DM option (Partner Managed Devices and Customer Managed Devices) for Non-Cisco 3rd party Devices via Cisco Public API integration, enabling them to cater to new and already deployed SIP devices at scale.
The Partner Managed Devices solution covers all third-party devices that comply with Cisco’s security and support requirements.
Key features and benefits of this integration include:
Seamless Asset Synchronization: Automatic syncing of assets, ensuring your Webex Organization structure and the User and Partner Managed Devices within these Organizations stay updated on both platforms.
Unified SIP Credential Management: Manage SIP credentials directly within Phonism. Any changes made are automatically synchronized with Webex and updated in the device configuration, eliminating redundancy and reducing error.
Device Configuration Data Synchronization: Pull device configuration data from Webex, allowing for a richer and more accurate device configuration experience in Phonism.
Ring-Ready Device Configuration: Devices are auto-configured to a ring-ready state using Phonism’s provided configuration templates. This ensures that the devices adhere to best practices and are ready for immediate use.
Integrating Phonism with Cisco's Webex enhances device management, streamlining operations and ensuring an optimized and current device ecosystem with minimal manual effort.
Currently, Phonism is the only approved and tested DM tool available for the Partner Managed Devices solution. Any other DM tool will have to be approved and tested by Cisco. Partners/Customers can reach out to webex-wholesale-pm@cisco.com for the same. For more information, see: https://phonism.com/customers/cisco-webex
2. Prerequisites
2.1 Phonism Requirements
Active Phonism account.
Account-level Super Admin User access.
E-mail sales@phonism.com and request a Phonism Account to be created for your company.
2.2 Webex by Cisco Requirements
Access to Partner-managed devices for Webex with a full administrator partner account.
Full Administrator of the owned organization.
Authorization to add Integrations from the Webex App Hub.
Authorization to create Service Apps in Webex.
Webex Calling
2.3 Additional Technical Requirements
Your Webex region must be known.
Device Managed Device feature enabled for the Partner Account
2.4 3rd Party Security Requirements
The Partner Managed Devices solution enables Webex Partners and Customers to seamlessly support non-Cisco SIP devices (phones, ATAs, and gateways) on the Webex platform, provided they adhere to Cisco's specified security and support criteria outlined below.
TLS 1.2 version supported for secure SIP.
A trust certificate is required for public key encryption. Refer to Webex Certificates' signing authority and Root CA required devices
Basic failover capabilities (single primary/secondary)
Support Cisco’s minimum Password security requirements
Active support from the Device Vendor
Webex Cloud Certification
Webex Calling
3. Installation and Setup
Phonism integrates with Webex by using two Webex Applications.
A Phonism Webex Integration App that will be available through the Webex App Hub. The App is responsible for syncing all the assets between Phonism and Webex.
A Webex Service App that has to be created and owned by the Webex Partner account. The App is responsible for syncing the config file of each device.
3.1 Adding the Integration App
Sign in to your Webex account, search for our integration on the Webex App Hub, and follow the instructions. Once you have a Phonism account and have successfully logged in, select this link to start https://app.phonism.com/integration/webex/wizzard
Upon redirection to Phonism, login to Phonism and continue the onboarding by following the on-screen wizard. The wizard will guide you through:
Login to Phonism
Check for Webex Authorization
Check permissions available in Webex
Summarize the assets to be synchronized
Finalize setup and begin synchronization
Note: You can synchronize the entire partner organization including yours, or selected organizations during this setup. These can be edited later on if needed in Phonism. (See section 4.1)
Once the integration is configured, Phonism begins asynchronously pulling users and phones in a new branch of your Phonism Hierarchy, automatically creating new Domains and Tenants within that branch representing each one of your Webex Organizations and Locations.
Click on Manage Phones / Start Managing Devices to be redirected
to Phonism.
3.2 Create a Service App in Control Hub
In addition to the Webex App Hub integration, Phonism needs additional access to retrieve device configuration metadata from Webex through a Service App.
The Partner Managed Devices solution will be enabled and available for all partners and customers. To enable the solution fully, the scope required to authorize the service app will require Cisco to enable the Partner Org. You can reach out to this email with your Partner/Customer org details to enable the feature, webex-wholesale-pm@cisco.com.
Log into Partner Hub Portal as Full Admin/Partner Admin
The goal is to create a ServiceApp User for the creation of the ServiceApp.
This is required to generate the API Tokens.
The Full Admin will also be able to approve the SA authorization.
Manually add users
** You're unable to add users who are already part of your organization or those who already possess a Webex account.
Email address: login+SA@phonism.com
Next
Ensure Call on Webex (1:1 call, non-PSTN)
Click Add Users
Log into the Developer site as the newly created ServiceApp User.
Click on My Webex Apps
Confirm you are logged in as the newly created ServiceApp User to create a Service App.
Click on Create Service App. The following series are screenshots of the Service App Creation process.
App name:
Phonism ServiceApp
Icon:
Optional
Description:
Optional “ServiceApp for Phonism Integration and creation for API Tokens.”
Select the scope: spark-admin:devices_config_read
*If this option is not available request access from: webex@phonism.com
The Service App has been created.
You must now request authorization for the newly created Service App.
Remember to note your new Service App's details. You will need this information when filling out Phonism's Integration Form.
Look at the newly created Service App and confirm authorization.
Review the scopes.
Click save.
Generate Tokens for the Phonism integration.
3.3 Adding the Service App
Once your service app is created, add the Service App information to your Webex Integration in Phonism.
To add the Service App (if not done in previous steps)
Go to the created Enterprise
Click on the Integration tab and edit the Webex integration.
From the Integrations tab at the Enterprise tier, select (Wholesale PMD) and click Edit. The root of the integration must exist at the Enterprise Level in Phonism. Add the API Client and Token Information from the Service App.
Fill the form values with the service App details created in step 3.2:
Client ID
Client secret
Access token
Refresh token
Device Info API URL: The API URL is used to pull device configuration data from Webex. It can be assigned globally for all the Organizations/Domains under the integration or can be assigned per Organization/Domain
Once synchronized, information from Webex Partner Hub should be visible in Phonism.
The Sync process started when you clicked Import Webex Data Into Phonism after the API Token was added.
You can sync all assets on demand by clicking “Sync Now” on the top bar or by clicking Sync on the Integration Record in the Integrations Enterprise section.
Each enabled Webex integration will be synchronized by default every 24 hours.
4. Use Cases and Functions
4.1 Hierarchy Synchronization
Phonism syncs the Webex hierarchy into Phonism, beginning from the Enterprise automatically created by adding the Webex Integration. Each Webex Organization corresponds to the respective Domain in Phonism and each Webex Location corresponds to the respective Tenant in Phonism.
Device Info File Per Organization
Each Organization/Domain can have a distinct device info file URL to pull device configuration data from Webex, it will depend on the region of each Webex Organization.
4.2 SIP Credential Management
In Partner Managed Devices, the Partner must handle SIP registration credentials. Through our integration, Phonism will manage SIP credentials for you, ensuring synchronization between Webex and the device.
When Phonism identifies a new Webex User associated with a Partner Managed Device, it will:
Create a new Phone at the appropriate Tenant in Phonism using the MAC in Webex
Please create a new User (Phonism treats Common Areas as Users) and associate it with the new Phone.
Retrieve and store device configuration metadata from Webex.
Create VoIP Credentials for each SIP Registration defined in Webex for the Device.
Generate passwords for corresponding SIP Registrations and update them in Webex.
Assign relevant VoIP Credentials to the Phone's corresponding Lines in Phonism.
4.3 Automatic Device Redirection
When a Redirect Service account is associated with Phonism, all related MACs added to your Phonism account are configured for automatic redirection to Phonism for a Zero-Touch Provisioning experience. This includes devices added via the Webex integration.
4.4 Automatic Device Configuration
For select devices (Device list TBD), when a Webex integration is added to your Phonism account, Phonism Templates will be automatically added at the root of your Webex integration.
These templates are optimized for Webex service, incorporating best practices and ensuring the device is configured to a ring-ready state.
For automatic template application to occur, you must do the following:
Navigate to the root of your Webex Integration in Phonism
Go to the Templates tab
Review each Template that was automatically imported
Update the Template State and set it to Auto Apply so that all relevant devices under this Hierarchy will have these Templates applied to them.
5. Changes in Behavior in Phonism
The following apply to Hierarchies and assets associated with a Webex integration:
5.1 Asset Creation, Updates, Deletions
Domains / Organizations:
Must be created in Webex Control Hub, they cannot be created in Phonism.
New organizations will be periodically synchronized into Phonism.
Organizations are read-only in Phonism.
Tenants / Locations:
They must be created in Webex Control Hub; they cannot be created in Phonism.
Updating the Tenant will only update the name of a Location in Webex.
Deleting a Tenant cannot be done in Phonism and must be done in Webex Control Hub.
Users / Users - Workspaces:
Creating a User from Phonism also creates a user in Webex, They will be created with a Webex Calling Pro license and extension associate.
Workspaces cannot be created from Phonism and must be created in the Webex by Cisco Control Hub.
Updating a User will update the corresponding user or workspace in Webex. For workspaces, updating the last name will update the name of the workspace in Webex. For users, updating the first name, last name, or/and email will update the corresponding value in Webex.
Deleting a User from Phonism also deletes the user or workspace in Webex.
Devices:
Creating a Phone from Phonism also creates a Phone in Webex. Assigning of a user is required on creation.
Updating a Phone will not have any impact on the corresponding Device in Webex.
Assigned users and extensions will be read-only after creation.
Deleting a Device from Phonism also deletes the device in Webex.
VoIP Credentials:
SIP usernames and authorization IDs will be pulled from Webex and both values will remain as read-only in Phonism.
Each VoIP username's password will be automatically generated and sent to Webex whenever a new SIP registration is retrieved through the integration.
Updating a VoIP credential password will update the password of the corresponding SIP registration in Webex.
5.2 Device Configuration from Webex
Webex provides a generic configuration file for Partner Managed Devices.
Phonism retrieves, parses, and stores these configuration values.
For select Phone models, these generic values are auto-converted into phone-compatible configurations. (Model list TBD)
For other phones, these values are accessible in Phonism via Phonism Tags for Phone and Template configuration.
5.3 Data Synchronization Interval
Phonism checks periodically for asset updates due to Webex API limitations.
Asset creations, updates, moves, and deletions are reflected in Phonism.
Updates of organizations, locations, users, workspaces, and devices are polled every 24 hours by default.
If a device requests a configuration file from Phonism, an on-demand synchronization check is performed, given that we have not done a synchronization check within a certain [period].
6. Removal of the Integration
6.1 Deletion of the Integration
If the integration is not for you and you have decided to back out, please follow these steps.
Remove the link first, this will keep any assets administered in the Webex instance intact. Account>Service Provider>Enterprise and select the trashcan on the right side.
You have the option to delete items in Phonism individually, or you can submit a ticket for us to completely remove the instance and its associated data.
7. Troubleshooting
7.1 Common Issues and Their Resolutions
Here are solutions for common issues you may face:
Problem: Integration isn't syncing.
Solution: Verify that your Service App's permissions are correctly set in Webex Control Hub. Also, check if your account has the correct access level in Phonism.
7.2 Locating Logs and Error Messages
To find logs and error messages:
Navigate to your Phonism account dashboard.
Click on the 'Logs' tab.
Filter by date, device, or error code for easier troubleshooting.
8. FAQ
8.1 Phonism Functionality with Webex by Cisco
Q: Does the integration auto-update?
A: Yes, Phonism periodically checks for updates from Webex and syncs any changes.
Q: Can I add organizations directly in Phonism?
A: No, all organizations MUST be added in Webex Control Hub first.
Q: Can I add locations directly in Phonism?
A: No, all locations MUST be added in Webex Control Hub first.
Q: Can I add users directly in Phonism?
A: Yes, users can be added from Phonism and it will be synced on Webex Control Hub.
Q: Can I add devices directly in Phonism?
A: Yes, devices can be added from Phonism and it will be pushed to Webex Control Hub. This can be done by adding manually a single phone, by importing a config file, or by a bulk import of a CSV file.
9. Additional Resources and Support
9.1 Documentation and Guides
For more detailed instructions and guides, visit the Phonism Documentation and Webex by Cisco Developer Documentation.
9.2 Contact Information for Support
For additional assistance, please open a support ticket.
10. Conclusion
10.1 Summary of the Integration and Its Benefits
Phonism's integration with Webex by Cisco simplifies device management for VoIP phones, maintaining seamless synchronization of hierarchy, users, devices, and VoIP credentials across both platforms. The integration optimizes device configurations for Webex operations, ensuring smooth functionality and enhanced user experience.