License usage

The license usage reports runLicenseReport and runUserReport provide visibility into an organization’s CloudBees CI usage to ensure it is compliant with its license entitlements. These reports provide an accurate list of unique CloudBees CI users across all their controllers during a time period.

For information about determining license usage at your site and examples of using these commands, refer to CloudBees CI license usage.

runLicenseReport

Returns the license information details for the specified controller or operations center.

When a CloudBees CI or operations center instance has several licenses, the one that applies is that with the greatest timestamp (timestamp in the event sent from CloudBees CI). There can be only one license in existence per controller_url at one time.

Arguments Descriptions

Arguments	Descriptions
instances	A controller or operations center URL. If an operations center URL is specified, data is returned for the specified operations center and the controllers attached to it. Determine the URL in one of the following ways: Via the UI: Navigate to Administration Configurations CI configurations, locate the desired controller or operations center and select its Server URL. Via the API: Use the getCIConfigurations API command to get a list of configurations. Parse the return response to select `serverURL` for the desired configuration. Argument type: string

instances

A controller or operations center URL. If an operations center URL is specified, data is returned for the specified operations center and the controllers attached to it. Determine the URL in one of the following ways:

Via the UI: Navigate to Administration Configurations CI configurations, locate the desired controller or operations center and select its Server URL.
Via the API: Use the getCIConfigurations API command to get a list of configurations. Parse the return response to select serverURL for the desired configuration.

Argument type: string

Positional arguments

None

Response

A licenses object is returned.

Field Description

Field	Description
instance_url	The URL of the instance that sent this license. Confirm format Type: string
expiresAt	The timestamp when this license expires. Type: date in `yyyy-mm-ddThh:mm:ss.MMM` format
startsAt	The timestamp when this license starts. Type: date in `yyyy-mm-ddThh:mm:ss.MMM` format
savedAt	The timestamp of this event. Type: date in `yyyy-mm-ddThh:mm:ss.MMM` format
registeredAt	The date this license has been stored in SDA database. Type: date in `yyyy-mm-dd` format
availableSeats	The number of available seats this license is entitled to. Type: number
remainingSeats	The number of remaining license seats for this license. Type: number

instance_url

The URL of the instance that sent this license. Confirm format

Type: string

expiresAt

The timestamp when this license expires.

Type: date in yyyy-mm-ddThh:mm:ss.MMM format

startsAt

The timestamp when this license starts.

Type: date in yyyy-mm-ddThh:mm:ss.MMM format

savedAt

The timestamp of this event.

Type: date in yyyy-mm-ddThh:mm:ss.MMM format

registeredAt

The date this license has been stored in SDA database.

Type: date in yyyy-mm-dd format

availableSeats

The number of available seats this license is entitled to.

Type: number

remainingSeats

The number of remaining license seats for this license.

Type: number

ec-perl

syntax: $cmdr->licenseReport({<instances>});

Example

$cmdr->licenseReport({instances => "https://my.controller.com"});▼

ectool

syntax: ectool licenseReport --instances

Example

ectool licenseReport --instances https://my.controller.com▼

runUserReport

This report produces a list of users based on the applied time filter. If the selected time period is undefined, it selects all users since the license started. A new user entry appears in the report when:

The user has logged in the CloudBees CI system in the selected period.
The user has committed in the CloudBees CI system in the selected period.

Arguments Descriptions

actualParamters

(Optional) The actual parameter values to support pagination and sort functionality in for form:

Argument type: String

beginDate

endDate

The start and end date of data to include in the user report.

If startDate is specified, then endDate must occur after beginDate.
If dates are not specified, the entire report is returned based on the last license period.

Argument type: date in the format yyyy-mm-ddThh:mm.

filters

A list of zero or more filter criteria definitions used to define objects to find.

Argument type: string

format

The format in which results are returned. Specify json or csv. If not provided, json is used.

Argument type: string

instances

(Required) One or more controller or operations center URLs. If an operations center URL is specified, data is returned for the specified operations center and the controllers attached to it. Determine the URL in one of the following ways:

Via the UI: Navigate to Administration Configurations CI configurations, locate the desired controller or operations center and select its Server URL.
Via the API: Use the getCIConfigurations API command to get a list of configurations. Parse the return response to select serverURL for the desired configuration.

Argument type: string

status

The current status of the email address. Specify one of <UNVERIFIED|VERIFIED>.

If not specified, all records for the specified email are returned.

Argument type: string

tool

(required) The capability for which results are returned.

The only capability currently supported with this report is ci.

Positional arguments

tool

Response

A list of users and their associated email address that have been using the platform. One record is returned for each user/email pair. There may be multiple user/email mappings for a given user.

Field Description

Field	Description
uuid	User identifier. Type: UUID
username	A name used to identify a user in the platform. Type: string
emails	Email address for the user.
lastLogin	The last time `username` signed in. Type: date in `yyyy-mm-dd` format
registeredAt	The first time `username` had been identified in the platform. Type: date in `yyyy-mm-dd` format
loginsCount	The number of times `username` has signed in. Type: number
primaryEmail	The primary email for the user. This is always empty for an unverified CloudBees CI user record. This may be empty for a verified CloudBees CI user record in the case where a CloudBees Software Delivery Automation user does not have a primary email.
fullUserName	Full user name for `username`. This is always empty for an unverified CloudBees CI user record. This may be empty for a verified CloudBees CI user record in the case where a CloudBees Software Delivery Automation user does not have a full user name.
verified	Whether email has been verified. Possible responses: `true`, `false`.

uuid

User identifier.

Type: UUID

username

A name used to identify a user in the platform.

Type: string

emails

Email address for the user.

lastLogin

The last time username signed in.

Type: date in yyyy-mm-dd format

registeredAt

The first time username had been identified in the platform.

Type: date in yyyy-mm-dd format

loginsCount

The number of times username has signed in.

Type: number

primaryEmail

The primary email for the user.

This is always empty for an unverified CloudBees CI user record.
This may be empty for a verified CloudBees CI user record in the case where a CloudBees Software Delivery Automation user does not have a primary email.

fullUserName

Full user name for username.

This is always empty for an unverified CloudBees CI user record.
This may be empty for a verified CloudBees CI user record in the case where a CloudBees Software Delivery Automation user does not have a full user name.

verified

Whether email has been verified. Possible responses: true, false.

ec-perl

syntax: $cmdr->userReport(<tool>, {<optionals>});

Example

$cmdr->userReport("ci", {instances => "https://my.controller.com"});▼

ectool

syntax: ectool userReport <tool> [optionals]

Example

ectool userReport "ci" --instances https://my.controller.com▼