Below lists the various interfaces that can be configured for Wrangler_ , test_mate, yarn_gate on the common Yarnman Photon Platform.
| Table of Contents | ||
|---|---|---|
|
Webex API
Add Interface
Login and Navigate to Interfaces > Add Interface
Select Webex API (OAuth2 - Cloud) as the Type
...
Select Permissions for Interface
test_mate_CV
This is a predefined list of Webex permissions that is used for Cloud Video testing, with webex and CVI (Cloud video interop)
...
Cisco Unified Communications Manager
This interface is used by Wrangler_ and test_mate to communicate with multiple services provided by the publisher or subscriber(s).
The following CUCM permissions are required for wrangler_
Standard CCM End Users
Standard Admin Users
Standard CCM Server Monitoring
Standard AXL API Access
| Note |
|---|
Standard AXL API Access Role may need to be added to a custom Access Control Group, an alternative approach is to use Standard CCM Super Users |
The following CUCM permissions are required for wrangler_ WxC-DI migrations
Before starting the migration, the source and target CUCM, and if required CUC, interfaces must be defined. The minimum Required access roles in the CUCM Application User for the AXL interface are
Source CUCM
| Info |
|---|
|
| Info |
|---|
To enable Read-Only access select the ‘Standard AXL API Users’ and ‘Standard AXL Read Only API Access’ roles refer to https://developer.cisco.com/docs/axl/#!authentication/using-basic-authentication as both roles are arequired for RO access |
| Note |
|---|
Standard AXL API Access Role may need to be added to a custom Access Control Group, an alternative approach is to use Standard CCM Super Users |
WxC-DI (Target) interface
As provided by Cisco with the following proviso if creating/ migrating Custom Access Control Groups in WxC-DI
| Note |
|---|
If migrating to WxC-DI, unless specifically requested, Cisco will assign an account with Rank 3 and no capability to read/ create Access Control Groups in WxC-DI target. So if Custom ACG’s need to be created, an account with these rights (Rank1) need to be requested from Cisco |
The following Permissions are required for test_mate
Standard CCM End Users
Standard Admin Users
Standard CTI Enabled
Standard CCM Server Monitoring
Standard CTI Allow Control of Phones supporting Rollover Mode
Standard CTI Allow Control of Phones supporting Connected Xfer and conf
Standard AXL API Access
| Note |
|---|
Standard AXL API Access Role may need to be added to a custom Access Control Group, an alternative approach is to use Standard CCM Super Users |
Create a new interface in yarnman
name the interface and press submit
Bind the interface to the required arm(s)
Press update/set Credentials
Type in the ip address of the publisher (this will automatically fill in the details to all the other services)
Type in the user and password, press use for all interfaces.
Press submit followed by test connection.
| Info |
|---|
the default cucm administrator account can not control jtapi devices |
Jade-Berlin
Whilst not technically an interface, this service provide jtapi control and uses the cucm interface within yarnman applications, mainly test_mate.
The jtapi.jar must be downloaded from the cucm.
This is done by navigating to Nodes > clicking on the node name > Pressing (re)download jtapi.jar 
Provide the ip address of the publisher, once jtapi.jar has downloaded press restart Jade-Berlin 
| Info |
|---|
Not all jtapi.jar versions are backwards compatible with different versions of CUCM - refer to https://developer.cisco.com/site/jtapi/jtapi-ucm-compatibility-matrix/ |
Common error messages from jtapi
Unable to create provider -- User connected on an invalid port
Most likely Secure CTI permission applied to the application user in cucm, remove secure CTI and only have standard cti
Unable to create provider -- connect timed out
This could be related to firewall or network connectivity between yarnman and cucm, CTI Manager not running on the target node
Unable to create provider -- bad login or password
Most likely wrong username/password/permission on the application user
Unable to create provider -- Incompatible Protocol version
The version of jtapi.jar cached in jade-berlin is not compatible with the target cucm, Download jtapi.jar from target cucm and restart jade-berlin
Unable to create provider -- directory login timeout
Can related to LDAP/AD timeout, high database load on cucm or jtapi not responding
Cisco Unity Connection UCXN Access
| Info |
|---|
Role
|
Webex API
Webex API uses OAuth2 to provide Access and Permissions to Webex API calls. An integration is created via the Webex developer portal that list the permissions and features (known as scopes in OAuth2). As part of the OAuth2 Process, a Webex User Authorises the integration with their Credentials which create the Tokens, No User/Pass are stored. The integration itself is just a list of permissions and doesn’t have access to Tokens. For more information visit https://developer.webex.com/docs/integrations for an overview.
| Note |
|---|
All Organisations (eg customers) The Webex user has access too will be granted with the Integration. This is a more likely Scenario when using Partner Hub, where the “Partner full admin” or “Partner admin” can have access to multiple customers. |
Add Interface
Login and Navigate to Interfaces > Add Interface
Select Webex API (OAuth2 - Cloud) as the Type
...
Select Permissions for Interface
Predefined scopes required for each feature, this page will mainly focus on Wrangler_ .
test_mate_CV
This is a predefined list of Webex permissions that is used for Cloud Video testing, with Webex and CVI (Cloud Video Interop) for further details https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2794225709
test_mate_WxC
This is predefined list of Webex permissions that is used with Webex Multi Tennant cloud calling, and requires the use of XSI to control phone endpoints registered to Webex. for further details https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2873851905
Wrangler_
This is predefined list of Webex permissions that is used with Webex Multi Tennant to read/write changes to an organisation.
...
The check Internet Access will verify the Proxy settings can reach webexapis.com, as well as the local browser can reach webex.com for the oAuth authentication flow.
...
reach webex.com for the oAuth authentication flow.
...
| Info |
|---|
in this context Client is your Web Browser connecting to webex , Server is Yarnman connecting to webexapis.com |
View Permissions required to be set up in Webex integration
...
Test Connection can be pressed to verify that Yarnman can access Webex API by requesting a simple about me API.
Enable Auto Access Token Refresh
From Version 2.6.10 there is a new feature toggle to enable the Access and Refresh token to be auto refreshed every 6days. Toggle this on the settings page of the interface and press Submit
Troubleshooting Scopes
Yarnman can help validate the scopes configured in your Webex app
...
The XSI is a special permission that may not be available on your webex Webex org, Yarnlab has an integration available for this to provide this function, see the following page for further information about the permissions for test_mate for webex Webex calling. https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2873851905
...
Troubleshooting Connectivity
For the Oauth OAuth Flow to Work Correctly, the Web browser you use needs to be able to access Webex (the Internet) and Yarnman.
...
| Code Block |
|---|
yarnman@ym-ph4-wxc-glen [ ~ ]$ curl --proxy-anyauth -x http://basicuser:basicuser123@10.101.10.87:3129 -4 "https://webexapis.com/" -I
HTTP/1.1 407 Proxy Authentication Required
Server: squid/4.13
Mime-Version: 1.0
Date: Wed, 13 Mar 2024 03:38:10 GMT
Content-Type: text/html;charset=utf-8
Content-Length: 3519
X-Squid-Error: ERR_CACHE_ACCESS_DENIED 0
Vary: Accept-Language
Content-Language: en
Proxy-Authenticate: Basic realm="Squid"
X-Cache: MISS from 18a6e4fa9a26
X-Cache-Lookup: NONE from 18a6e4fa9a26:3129
Via: 1.1 18a6e4fa9a26 (squid/4.13)
Connection: keep-alive
HTTP/1.1 200 Connection established
HTTP/1.1 401 Unauthorized
x-content-type-options: nosniff
trackingid: ROUTERGW_cc737ef5-1e1d-4e2f-8a1e-840dd944250f
vary: accept-encoding
content-type: application/json
date: Wed, 13 Mar 2024 03:38:11 GMT
server: istio-envoy
x-envoy-upstream-service-time: 3
transfer-encoding: chunked |
Cisco Unified Communications Manager
This interface is used by Wrangler_ and test_mate to communicate with multiple services provided by the publisher or subscriber(s).
The following CUCM permissions are required for wrangler_
Standard CCM End Users
Standard Admin Users
Standard CCM Server Monitoring
Standard AXL API Access
| Note |
|---|
Standard AXL API Access Role may need to be added to a custom Access Control Group, an alternative approach is to use Standard CCM Super Users |
The following Permissions are required for test_mate
Standard CCM End Users
Standard Admin Users
Standard CTI Enabled
Standard CCM Server Monitoring
Standard CTI Allow Control of Phones supporting Rollover Mode
Standard CTI Allow Control of Phones supporting Connected Xfer and conf
Standard AXL API Access
| Note |
|---|
Standard AXL API Access Role may need to be added to a custom Access Control Group, an alternative approach is to use Standard CCM Super Users |
Create a new interface in yarnman
name the interface and press submit
Bind the interface to the required arm(s)
Press update/set Credentials
Type in the ip address of the publisher (this will automatically fill in the details to all the other services)
Type in the user and password, press use for all interfaces.
Press submit followed by test connection.
| Info |
|---|
the default cucm administrator account can not control jtapi devices |
Jade-Berlin
Whilst not technically an interface, this service provide jtapi control and uses the cucm interface within yarnman applications, mainly test_mate.
The jtapi.jar must be downloaded from the cucm.
This is done by navigating to Nodes > clicking on the node name > Pressing (re)download jtapi.jar
Provide the ip address of the publisher, once jtapi.jar has downloaded press restart Jade-Berlin
| Info |
|---|
Not all jtapi.jar versions are backwards compatible with different versions of cucms. |
Common error messages from jtapi
Unable to create provider -- User connected on an invalid port
Most likely Secure CTI permission applied to the application user in cucm, remove secure CTI and only have standard cti
Unable to create provider -- connect timed out
This could be related to firewall or network connectivity between yarnman and cucm, CTI Manager not running on the target node
Unable to create provider -- bad login or password
Most likely wrong username/password/permission on the application user
Unable to create provider -- Incompatible Protocol version
The version of jtapi.jar cached in jade-berlin is not compatible with the target cucm, Download jtapi.jar from target cucm and restart jade-berlin
Unable to create provider -- directory login timeout
...
-time: 3
transfer-encoding: chunked |
MSGraph
This is used to access o365 calendaring information for test_mate Cloud Video. This also uses OAuthv2, but more in a API key method
a ClientID and ClientSecret are required, which are provisioned in Microsoft Entra ID (formerly Azure Active Directory) with the required permissions and access. The API key will expire after a period of time, usually 180days (this depends on the customers security policy)
Microsoft Graph | Type |
|---|---|
Calendars.Read | Application |
Calendars.ReadWrite | Application |
OnlineMeetingArtifact.Read.All | Application |
OnlineMeetings.Read.All | Application |
OnlineMeetings.ReadWrite.All | Application |
User.Read.All | Application |
CallRecords.Read.All | Application |
| Note |
|---|
The API Key created should be limited to only the meeting room mailboxes/resources https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access |
Select the Microsoft Graph API as the interface type, Configure a Proxy if required in the environment. Bind the Arm to the yarnman server.
Press Update/Set credentials enter in the AppID, AppKey and default microsoft TenantID
...
Pressing Test connection will return a list of users if successful
PRTG
Currently used with yarn_gate to allow a HTTP push to Paessler PRTG for scheduled tasks results.
Select PRTG as the interface type, provide a description and the HTTP/S PRTG Sensor Address.
| Info |
|---|
This interface supports both HTTP and HTTPS for the server address, depending on the PRTG sensor setup. |
...
Click on Arm bindings to bind this to a yarnman server(s)