License usage

3 minute readReference

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.

runLicenseReport

Returns the license information details for the specified controller or operation 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 CI). There can be only one license in existence per controller_url at one time.

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

Positional arguments

None

Response

A licenses object is returned.

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

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 CI system in the selected period.

  • The user has committed in the CI system in the selected period.

Arguments Descriptions

tool

(required) The capability for which results are returned. Specify cd, ci, sda.

The only capability currently supported with this report is ci.

Argument type: string

Optional parameters

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.

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

format

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

Argument type: string

Positional arguments

tool

Response

A list of users that have been using the platform.

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

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