Yeastar Management Plane - Version 2.0

Modified on Wed, 26 Aug at 11:14 AM

Overview

The Yeastar Management Plane - Version 2.0 collector retrieves Cloud PBX instance data from the Yeastar Management Platform (YMP) using the YMP Open API.

This collector provides visibility into each Cloud PBX instance’s extension capacity, concurrent call capacity, call recording capacity, and activation status, enabling service providers to validate PBX subscriptions and allocate costs within Varibill.

The collector retrieves unrated allocation data, meaning no monetary values are supplied by the source system. Pricing and billing calculations are applied within Varibill based on configured contracts and pricing rules.

This is a point-in-time collector, meaning each execution retrieves the current state of PBX instances and their capacity allocations at the time of collection.

For general instructions on creating and running Source Collectors, see: Configuring a New Cloud Source Collector

Collector Summary

Field	Value
Source Collector Name	Yeastar Management Plane - Version 2.0
Collection Behavior	Point in Time
Rating Model	Unrated
Vendor Name	Yeastar
Product	Yeastar Management Platform (YMP)
Purpose	Retrieves Cloud PBX instance allocation data from the Yeastar Management Platform for billing and allocation within Varibill

About Yeastar Management Platform

Yeastar Management Platform (YMP) is a cloud-hosted management console used by service providers and managed service providers to deploy, manage, and monitor Yeastar Cloud PBX instances across their customer base.

Each Cloud PBX instance represents an individual customer’s hosted phone system. YMP tracks each instance’s status, extension capacity, concurrent call capacity, and call recording capacity. Service providers use YMP to centrally manage their entire Cloud PBX portfolio from a single administrative portal.

Note: Yeastar documentation for the YMP Open API is available via the YMP API Overview.

Data Collected

The Yeastar Management Plane - Version 2.0 collector retrieves unrated Cloud PBX instance allocation data from the Yeastar Management Platform. The collector queries all PBX instances, filters to those with a status of Running, and can produce up to seven types of records. Each type is independently enabled or disabled using a collection switch parameter.

Record Type	Description	Quantity	Collection Switch
PBX Instances	One record per running PBX instance	1	Collect PBX Instances
Extensions	The total extension capacity allocated to the PBX instance	Extension count	Collect Extensions
Free Concurrent Call Capacity	The number of concurrent calls included at a ratio of 1 per 4 extensions	Extensions / 4	Collect Free Concurrent Call Capacity
Excess Concurrent Call Capacity	Concurrent calls allocated above the included amount	Total concurrent calls minus included amount	Collect Excess Concurrent Call Capacity
All Recordings	The total call recording capacity allocated to the PBX instance	Recording capacity value	Collect All Recordings
Free Recordings	The included call recording capacity, capped at 500	Minimum of recording capacity and 500	Collect Free Recordings
Excess Recordings	Call recording capacity above the included 500	Recording capacity minus 500	Collect Excess Recordings

The identifiers submitted to Varibill for each record are constructed as follows:

Product Identifier — constructed as {Product Identifier Prefix}#Activated or {Product Identifier Prefix}#Unactivated, depending on whether the PBX instance is active. Each record type uses a separate prefix configured in the collector parameters. For example, with a prefix of YMPExt, the Product Identifier would be YMPExt#Activated for an active instance.
Client Identifier — the PBX instance’s numeric ID from the Yeastar Management Platform
Record Identifier — a description of the data type and the PBX instance name (for example, Number of extensions for PBX Acme Corp, PBX instance for Acme Corp, Number of concurrent calls included with 1 concurrent call per 4 extensions, Concurrent calls exceeding 1 concurrent call per 4 extensions, Call recording capacity for PBX Acme Corp, Included call recording capacity, or Additional call recording capacity)
Unique Identifier — the PBX instance’s numeric ID

Records are automatically excluded in the following cases:

Extension records are excluded when the extension count is zero.
Free concurrent capacity records are excluded when the calculated quantity is zero (the PBX has fewer than 4 extensions).
Excess concurrent capacity records are excluded when there are no concurrent calls above the included amount.
All recording, free recording, and excess recording records are excluded when call recording is not enabled on the PBX instance.
All recording records are additionally excluded when the recording capacity is zero.
Excess recording records are excluded when the recording capacity is 500 or less (no excess above the included amount).
Free recording records are excluded when the recording capacity is zero.

Note: Only PBX instances with a status of Running are included in the collected data. Instances in other states (for example, suspended or stopped) are excluded.

Note: The Yeastar Management Plane - Version 2.0 collector reflects the state of the Yeastar Management Platform at the time it runs. PBX instance changes between collection runs will be reflected in the next execution.

Prerequisites

Before configuring this collector, ensure that:

You have administrator access to the Yeastar Management Platform portal
The YMP API feature has been enabled within the YMP portal
You have generated or located the Client ID and Client Secret values from the API settings
You have noted the host URL of your YMP portal (for example, https://ymp.example.com)
You have access to the Varibill Source Collector configuration screen

Tip: If your Client Secret is compromised, regenerate it from the YMP portal. Regenerating the secret will invalidate any existing access tokens.

Warning! The YMP Client Secret grants API access to your Yeastar environment. Store it securely and do not share it. The secret is masked in the Varibill UI once saved. If it is compromised, regenerate it immediately from the YMP portal.

Configuration Parameters

The parameters below are entered when configuring the collector in Varibill. They are grouped by function.

Connection Parameters

These parameters identify and authenticate against your Yeastar Management Platform instance using OAuth 2.0 client credentials.

Parameter	What it is	Where to find it
YMP Host	The base URL of your Yeastar Management Platform portal	Your YMP administrator. Format: `https://ymp.example.com` (include `https://`, no trailing slash)
YMP Client ID	The Client ID generated in the YMP API settings	YMP portal API settings
YMP Client Secret	The Client Secret generated in the YMP API settings	YMP portal API settings

Warning! The YMP Client Secret is a sensitive credential. It is masked in the Varibill UI once saved. If it is compromised, regenerate it immediately from the YMP portal.

Collection Switches

These boolean parameters control which data types are collected. Each switch independently enables or disables a specific record type. When a switch is set to false, the corresponding data type is not collected.

Parameter	What it enables	Default
Collect PBX Instances	Collects one record per running PBX instance	`false`
Collect Extensions	Collects extension capacity per PBX instance	`false`
Collect Free Concurrent Call Capacity	Collects the included concurrent call capacity (1 per 4 extensions)	`false`
Collect Excess Concurrent Call Capacity	Collects concurrent call capacity above the included amount	`false`
Collect All Recordings	Collects total call recording capacity per PBX instance	`false`
Collect Free Recordings	Collects the included call recording capacity (capped at 500)	`false`
Collect Excess Recordings	Collects call recording capacity above the included 500	`false`

Note: At least one collection switch must be enabled for the collector to produce output. All switches default to false.

Product Identifier Parameters

Each data type uses a separate Product Identifier prefix.

Parameter	What it is	Example
PBX Instance Product Identifier	Product Identifier prefix for PBX instance records	`YMPPBXInstance`
Extension Code Product Identifier	Product Identifier prefix for extension allocation records	`YMPExt`
Free Concurrent Capacity Product Identifier	Product Identifier prefix for included concurrent call capacity records	`YMPFreeConcurrent`
Excess Concurrent Capacity Product Identifier	Product Identifier prefix for excess concurrent call capacity records	`YMPExcessConcurrent`
Recording Code Product Identifier	Product Identifier prefix for total call recording capacity records	`YMPRecording`
Free Recording Code Product Identifier	Product Identifier prefix for included call recording capacity records	`YMPFreeRecording`
Excess Recording Code Product Identifier	Product Identifier prefix for excess call recording capacity records	`YMPExcessRecording`

Operational Parameters

These parameters control file management behavior.

Parameter	What it is	Default
Delete data files older than	The number of days after which locally stored collection files are automatically deleted. Must be at least 1.	`62`
Maximum number of records per file	The maximum number of records written to a single output file before a new file is started. Must be between 1,000 and 50,000.	`10000`

Configuration Steps

Step 1: Prepare Yeastar Management Platform

Log in to the YMP portal as an administrator.
Navigate to the API settings section.
Enable the API feature if it is not already enabled.
Copy the Client ID value.
Copy the Client Secret value.
Note the host URL of your YMP portal.

For detailed instructions, see the YMP API Overview.

Step 2: Configure the Collector in Varibill

In the Varibill User Interface, open the Source Collector configuration screen.
Enter the required field values under the Details tab:
- Hosting Provider: Select Varibill Cloud
- Source Collector Name: Select Yeastar Management Plane - Version 2.0
Enter the connection parameters:
- YMP Host: The base URL of your YMP portal (for example, https://ymp.example.com)
- YMP Client ID: The Client ID from the YMP API settings
- YMP Client Secret: The Client Secret from the YMP API settings
Enable the collection switches for the data types you want to collect:
- Collect PBX Instances: Set to true to collect PBX instance records
- Collect Extensions: Set to true to collect extension capacity records
- Collect Free Concurrent Call Capacity: Set to true to collect included concurrent call capacity
- Collect Excess Concurrent Call Capacity: Set to true to collect excess concurrent call capacity
- Collect All Recordings: Set to true to collect total call recording capacity
- Collect Free Recordings: Set to true to collect included call recording capacity
- Collect Excess Recordings: Set to true to collect excess call recording capacity
Enter the Product Identifier prefix for each enabled data type:
- PBX Instance Product Identifier: The prefix for PBX instance records (for example, YMPPBXInstance)
- Extension Code Product Identifier: The prefix for extension records (for example, YMPExt)
- Free Concurrent Capacity Product Identifier: The prefix for included concurrent call records (for example, YMPFreeConcurrent)
- Excess Concurrent Capacity Product Identifier: The prefix for excess concurrent call records (for example, YMPExcessConcurrent)
- Recording Code Product Identifier: The prefix for total call recording records (for example, YMPRecording)
- Free Recording Code Product Identifier: The prefix for included call recording records (for example, YMPFreeRecording)
- Excess Recording Code Product Identifier: The prefix for excess call recording records (for example, YMPExcessRecording)
Save the collector configuration.

Step 3: Run the Collector

Run or schedule the collector according to your standard Source Collector execution process.

For detailed instructions, see: Configuring a New Cloud Source Collector

Troubleshooting

If the collector fails to connect to the Yeastar Management Platform, verify that:

The YMP Host URL is correct and includes https:// with no trailing slash.
The YMP Client ID is correct.
The YMP Client Secret is valid and has not been regenerated since it was last configured.
The YMP API feature is enabled in the YMP portal.
No firewall or IP restriction rules are blocking the Varibill collector’s IP address.

If the collector connects successfully but returns no data, verify that:

At least one collection switch is set to true.
There are active PBX instances with a status of Running in your YMP environment.
The PBX instances have non-zero values for the enabled data types (records with zero values are automatically excluded).
For call recording data types, confirm that call recording is enabled on the PBX instances you expect to see.

Yeastar References

The following resources may assist with locating values or configuring your Yeastar Management Platform API access.

Yeastar Documentation (External)

Note: Yeastar documentation is provided for reference. Steps and interface labels may vary depending on your YMP version and account permissions.