Below lists the various interfaces that can be configured for Wrangler_ , test_mate, yarn_gate on the common Yarnman Photon Platform.
| Table of Contents | ||
|---|---|---|
|
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.
| Info |
|---|
The same interface can be used for Wrangler_ and test_mate, but each |
requires different Scope permissions, its recommended to use an interface for wrangler_ and another for test_mate. |
This example will show setting up Wrangler_ for Webex Scopes.
Toggle the wrangler_WxC permission and Press Submit
...
| Info |
|---|
Proxy is optional, ; Internet access is required to access https://webexapis.com/ from Yarnman. |
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.
...
| 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
When the page saves, Press show press Show Scopes
These are the requires required roles to be configured on your webex Webex integration
...
Create Webex Integration
Open a new Tab/Browser to Create a new Webex integration: https://developer.webex.com/my-apps
...
| Note |
|---|
Service intergration integration with static auth_token are is not supported at this time |
Set Webex permissions
Complete the required fields (we will come back to the redirect uriURI), select or upload a logo, and scroll down to select choose the scopes to match the ones shown from Yarnman.
...
Find Redirect URL from yarnman
Switch back to Yarnman and select the Arm Bindings tab
Select the Yarnman node in the dropdown, followed by pressing Bind to Arm
...
Save redirect URL in Webex integration.
Copy the URL that is shown as Redirect URL and switch back to Webex
Paste in the URl URL to the URL field, and make sure to remove any leading Spaces or Tabs that may come through
...
Save Integration and obtain a Client ID and Secret
Press Add in Webex
Make note of the Client ID, Client Secret ( NOTE: this won;'t be shown again , however it can be regenerated if lost)
...
Start oAuth flow with Set Credentials
Switch back to Yarnman
press Press Update / Set Credentials
Populate
Application with either the same as your you called it in Webex or something meaningful.
Client ID as string provided by Webex
Redirect URI as the one provided supplied by yarnman and press submit
...
The popup will refresh with an Authorise button with the confirmed details, ; Press Authorise to obtain the OAuth Token
...
| Note |
|---|
The web browser will required require Internet Access and Access to Yarnman, The Test . Please make sure your Jumpbox or Proxy settings in the browser allow for this configuration. If you have a proxy in your browser, you may need to bypass the Yarnman's IP address of Yarnman if you have a proxy in your browser. |
The webex Webex authentication screen will be presented. Depending on your environment, this could be handled by Webex or your SSO provider. Eg , Such as Microsoft.
Webex will prompt you to allow or deny the permissions associated with your account.
...
Press accept and log back into yarnman when it redirects
Paste in the Client secret
...
Token details will be stored.
...
Test Connection can be pressed to verify that Yarnman can access Webex API doing by requesting a simple about me api requestAPI.
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 Webex app
Copy the whole URL from webexWebex
...
Press Validate Scopes in Yarnman
...
Paste the URL in the popup from Yarnman.
...
Press validate, and Yarnman will advise the roles that need to be checked on the webex Webex app
...
XSI Permission not found
The XSI is a special permission that may not be available on your 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 calling. https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2873851905
| Note |
|---|
Yarnlab do NOT need to know the webex credentials |
Contact Yarnlab support to get an integration created https://support.yarnlab.io/ or support@yarnlab.io
Provide Yarnlab with the redirect URL provided on the interface page as per below, This will be unique per interface added and if multiple organisations/interfaces are being tested multiple redirect URLs will need to be provided
...
Troubleshooting Webex login
Where possible its , it's best to use an a Private/Incognito session to preform perform the oAuth flow. As there There could be issues with cached logins with SSO , or the wrong SSO id ID being prompted and , causing the oAuth to fail with a change of UserID midsession.
Troubleshooting Connectivity
For the OAuth Flow to Work Correctly, the Web browser you use needs to be able to access Webex (the Internet) and Yarnman.
DNS
Below shows the yarnman server is not able to resolve the DNS
| Code Block |
|---|
yarnman@ym-ph4-wxc-glen [ ~ ]$ curl "https://webexapis.com" -I
curl: (6) Could not resolve host: webexapis.com
yarnman@ym-ph4-wxc-glen [ ~ ]$ |
Check DNS servers used by the yarnman server (do not edit this file)
| Code Block |
|---|
yarnman@ym-ph4-wxc-glen [ ~ ]$ cat /run/systemd/resolve/resolv.conf
# This is /run/systemd/resolve/resolv.conf managed by man:systemd-resolved(8).
# Do not edit.
#
# This file might be symlinked as /etc/resolv.conf. If you're looking at
# /etc/resolv.conf and seeing this text, you have followed the symlink.
#
# This is a dynamic resolv.conf file for connecting local clients directly to
# all known uplink DNS servers. This file lists all configured search domains.
#
# Third party programs should typically not access this file directly, but only
# through the symlink at /etc/resolv.conf. To manage man:resolv.conf(5) in a
# different way, replace this symlink by a static file or a different symlink.
#
# See man:systemd-resolved.service(8) for details about the supported modes of
# operation for /etc/resolv.conf.
nameserver 10.0.0.1
search lab.yarnlab.io |
to change the DNS servers, in this example, we are replacing the single DNS server with multiple DNS servers
You must first log in as the root user to modify system settings using su. exit out from the root when you are done
| Code Block |
|---|
yarnman@ym-ph4-wxc-glen [ ~ ]$ su
Password:
root@ym-ph4-wxc-glen [ /var/home/yarnman ]# netmgr dns_servers --set --mode static --servers 8.8.8.8,8.8.4.4
root@ym-ph4-wxc-glen [ /var/home/yarnman ]# exit |
| Code Block |
|---|
yarnman@ym-ph4-wxc-glen [ ~ ]$ cat /run/systemd/resolve/resolv.conf # This is /run/systemd/resolve/resolv.conf managed by man:systemd-resolved(8). # Do not edit. # # This file might be symlinked as /etc/resolv.conf. If you're looking at # /etc/resolv.conf and seeing this text, you have followed the symlink. # # This is a dynamic resolv.conf file for connecting local clients directly to # all known uplink DNS servers. This file lists all configured search domains. # # Third party programs should typically not access this file directly, but only # through the symlink at /etc/resolv.conf. To manage man:resolv.conf(5) in a # different way, replace this symlink by a static file or a different symlink. # # See man:systemd-resolved.service(8) for details about the supported modes of # operation for /etc/resolv.conf. nameserver 8.8.8.8 nameserver 8.8.4.4 search lab.yarnlab.io |
Test to validate yarnman can reach webexapis.com, note 401 error as we are trying to browse without any credentials
Test Direct Access
| Code Block |
|---|
yarnman@ym-ph4-wxc-glen [ ~ ]$ curl "https://webexapis.com" -I
HTTP/1.1 401 Unauthorized
x-content-type-options: nosniff
trackingid: ROUTERGW_5fdd5b92-b77f-40af-9f46-ceae729d74ba
vary: accept-encoding
content-type: application/json
date: Wed, 13 Mar 2024 03:22:59 GMT
server: istio-envoy
x-envoy-upstream-service-time: 1
transfer-encoding: chunked
|
Proxy
Depending on your environment, yarnman may also need to be able to resolve the proxy if a FQDN is required to the proxy server
You can verify yarnman can reach the proxy using curl, the http1.1 200 connection established shows the connection to the proxy was successful
Proxy without Auth
| Code Block |
|---|
yarnman@ym-ph4-wxc-glen [ ~ ]$ curl --proxy "http://10.101.10.87:3130" "https://webexapis.com/" -I
HTTP/1.1 200 Connection established
HTTP/1.1 401 Unauthorized
x-content-type-options: nosniff
trackingid: ROUTERGW_2c5c1133-6586-42d2-a9cd-afaca8842baa
vary: accept-encoding
content-type: application/json
date: Wed, 13 Mar 2024 03:25:18 GMT
server: istio-envoy
x-envoy-upstream-service-time: 2
transfer-encoding: chunked |
Proxy showing user/pass is required
Proxy server requires a user/pass to connect, with the 407 error
| Code Block |
|---|
yarnman@ym-ph4-wxc-glen [ ~ ]$ curl --proxy "http://10.101.10.87:3129" "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:26:32 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
curl: (56) CONNECT tunnel failed, response 407 |
Proxy showing user/pass to the proxy
the first 407 tells curl to try again with user:pass, 200 connect is successful to the proxy followed by the 401 to webex as expected.
| 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 |
FedRamp Support for Wrangler WxC-MT
Added in 2.6.13
FedRamp support is now availible for wrangler_ WxC-MT migrations only https://developer-usgov.webex.com/docs/platform-introduction
| Note |
|---|
It is not support supported for test_mate Cloud Video or test_mate WxC-MT due to API restrictions |
...
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)