The license usage reports, licenseReport and userReport, 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.
To try out these reports via the REST API endpoint, scroll to the report section of the CloudBees Software Delivery Automation swagger playground found here: https://<cloudbees-cdro-server>/rest/doc/v1.0/. See Using the RESTful API for complete information about accessing the CloudBees Software Delivery Automation RESTful API.
To try them out from a command line, see the licenseUsage commands. See CloudBees Software Delivery Automation command line access for complete information about command line access to CloudBees Software Delivery Automation APIs.
License report
The license report returns the license information details for a CloudBees CI controller or an operations center. When a CloudBees CI or operations center instance has several licenses, the one that applies is the last one, that is, the one with the newest timestamp sent from CloudBees CI. There can be only one license in existence per controller at one time.
End points
- REST API endpoint
https:<cloudbees-cd-server>/rest/v1.0/runLicenseReport
- ectool command
ectool runLicenseReport
Request and response formats
For complete information about request parameters and response format, see runLicenseReport.
licenseReport example
Using the REST API:
JSON response: https://<cloudbees-cdro-server>/rest/v1.0/runLicenseReport
Using ectool command line interface:
XML response: ectool runLicenseReport JSON response: ectool --format json runLicenseReport
- Response body
-
The response body example below shows 15 available seats, 2 active users, 13 remaining seats
<response requestId="1" nodeId="10.0.0.23"> <result> <total>12</total> <availableSeats>15</availableSeats> <startsAt>2021-04-30T00:00:00.000Z</startsAt> <controllerUrl>http://[cloudbees-ci-controller]</controllerUrl> <activeUsers>2</activeUsers> <savedAt>2021-04-30T17:51:14.397Z</savedAt> <remainingSeats>13.00</remainingSeats> <url>http://[cloudbees-ci-controller]</url> <url_count>12</url_count> <expiresAt>2021-05-14T23:59:59.000Z</expiresAt> </result> </response>
{ "result": [ { "total": "10", "availableSeats": "15", "startsAt": "2021-04-30T00:00:00.000Z", "controllerUrl": "[cloudbees-ci-controller]", "activeUsers": "2", "savedAt": "2021-04-30T17:51:14.397Z", "remainingSeats": "13.00", "url": "[cloudbees-ci-controller]", "url_count": "10", "expiresAt": "2021-05-14T23:59:59.000Z" } ] }
- Confirmation from the Jenkins user dashboard
-
Screenshot below from the Jenkins user dashboard confirms a license for 15 users.
User report
The user 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 selected period and it has triggered a new build.
Endpoints
- REST API endpoint
https:<cloudbees-cd-server>/rest/v1.0/runUserReport[&optional-query-parameters]
- ectool command
ectool runUserReport [optional parameters]
Request and response formats
For complete information about request parameters and response format, see runUserReport.
userReport example
Using the REST endpoint.
XML: https://<cloudbees-cdro-server>/rest/v1.0/runUserReport?format=xml JSON: https://<cloudbees-cdro-server>/rest/v1.0/runUserReport?format=json CSV: https://<cloudbees-cdro-server>/rest/v1.0/runUserReport?format=csv
Using the ectool command line interface.
XML: ectool runUserReport JSON: ectool --format json runUserReport CSV: ectool runUserReport --format csv
Response body includes user information for the two active users.
<responses version="2.3" dispatchId="4857" nodeId="10.0.0.23"> <response requestId="1" nodeId="10.0.0.23"> <result> <lastLogin>1620330412892.00</lastLogin> <loginsCount>4.00</loginsCount> <lastLogin_label>2021-05-06T19:46:52.892Z</lastLogin_label> <id>b642b421-7b34-31e8-93bd-915fc65c4452</id> <category>login</category> <email>test@test.com</email> <status>success</status> <username>test</username> </result> <result> <lastLogin>1620325991029.00</lastLogin> <loginsCount>2.00</loginsCount> <lastLogin_label>2021-05-06T18:33:11.029Z</lastLogin_label> <id>77986701-a1b4-3385-b4e0-7ed70be36f67</id> <category>login</category> <email>admin@cloudbees.com</email> <status>success</status> <username>admin</username> </result> </response> </responses>
{ "requestId" : "1", "result" : [ { "email" : "test@test.com", "lastLogin_label" : "2021-05-06T19:46:52.892Z", "status" : "success", "loginsCount" : "4.00", "lastLogin" : "1620330412892.00", "category" : "login", "id" : "b642b421-7b34-31e8-93bd-915fc65c4452", "username" : "test" }, { "email" : "admin@cloudbees.com", "lastLogin_label" : "2021-05-06T18:33:11.029Z", "status" : "success", "loginsCount" : "2.00", "lastLogin" : "1620325991029.00", "category" : "login", "id" : "77986701-a1b4-3385-b4e0-7ed70be36f67", "username" : "admin" } ] }
lastLogin,loginsCount,lastLogin_label,id,category,email,status,username 1620330412892.00,4.00,2021-05-06T19:46:52.892Z,"b642b421-7b34-31e8-93bd-915fc65c4452",login,test@test.com,success,test 1620325991029.00,2.00,2021-05-06T18:33:11.029Z,"77986701-a1b4-3385-b4e0-7ed70be36f67",login,admin@cloudbees.com,success,admin
- Confirmation from Jenkins Users dashboard
-
Screenshot below from the Jenkins user dashboard confirms two active users.
