CloudBees CI license usage reports

3 minute readDeveloper productivityData analytics

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 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/. Refer to Using the CloudBees CD/RO RESTful API for complete information about accessing the CloudBees Software Delivery Automation RESTful API.

To try them from a command line, refer to the licenseUsage commands. Refer to 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 the operations center. When a CloudBees CI or the operations center instance has several licenses, the most recent one is applied, that is, the one with the newest timestamp sent from CloudBees CI. There can be only one license in existence per controller at a 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, refer to 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

XML
Json
<response requestId="1" nodeId="10.0.0.23">
<result>
      <availableSeats>10</availableSeats>
      <activeUsers>0</activeUsers>
      <remainingSeats>10.00</remainingSeats>
      <url>http://10.30.176.203:8080</url>
      <customerName>CloudBees Test</customerName>
      <expiresAt>2021-08-28T23:59:59.000Z</expiresAt>
      <wildcard>false</wildcard>
      <controllerUrl>http://10.30.176.203:8080/</controllerUrl>
      <startsAt>2021-08-06T00:00:00.000Z</startsAt>
      <licenseVersion>3</licenseVersion>
      <savedAt>2021-08-06T12:44:08.594Z</savedAt>
      <licensedPacks>
            [1.3.6.1.4.1.38143.1.11.14,
            1.3.6.1.4.1.38143.1.11.13, ...]
      </licensedPacks>
      <organizationalUnit>cloudbees.com</organizationalUnit>
    </result>
    <result>
      <availableSeats>15</availableSeats>
      <activeUsers>12</activeUsers>
      <remainingSeats>3.00</remainingSeats>
      <url>http://10.30.176.75:8080</url>
      <customerName>CloudBees Inc</customerName>
      <expiresAt>2021-08-21T23:59:59.000Z</expiresAt>
      <wildcard>true</wildcard>
      <controllerUrl>http://10.30.176.75:8080/</controllerUrl>
      <startsAt>2021-08-03T00:00:00.000Z</startsAt>
      <licenseVersion>3</licenseVersion>
      <savedAt>2021-08-04T11:25:00.970Z</savedAt>
      <licensedPacks>
            [1.3.6.1.4.1.38143.1.11.14,
            1.3.6.1.4.1.38143.1.11.13, ...]
      </licensedPacks>
      <organizationalUnit>cloudbees.com</organizationalUnit>
    </result>
  </response>
{
   "result":[
      {
         "availableSeats":"10",
         "activeUsers":"0",
         "remainingSeats":"10.00",
         "url":"xxxxxx",
         "customerName":"CloudBees Test",
         "expiresAt":"2021-08-28T23:59:59.000Z",
         "wildcard":"false",
         "controllerUrl":"xxxxx",
         "startsAt":"2021-08-06T00:00:00.000Z",
         "licenseVersion":"3",
         "savedAt":"2021-08-06T12:44:08.594Z",
         "licensedPacks":"
            [1.3.6.1.4.1.38143.1.11.14,
            1.3.6.1.4.1.38143.1.11.13, ...]",
         "organizationalUnit":"xxxxx"
      },
      {
         "availableSeats":"15",
         "activeUsers":"12",
         "remainingSeats":"3.00",
         "url":"http://xxxxxxx",
         "customerName":"CloudBees Inc",
         "expiresAt":"2021-08-21T23:59:59.000Z",
         "wildcard":"true",
         "controllerUrl":"xxxxxx",
         "startsAt":"2021-08-03T00:00:00.000Z",
         "licenseVersion":"3",
         "savedAt":"2021-08-04T11:25:00.970Z",
         "licensedPacks":"[1.3.6.1.4.1.38143.1.11.14, 1.3.6.1.4.1.38143.1.11.13, ...]",
         "organizationalUnit":"xxxxx"
      }
  ]
}
Confirmation from the CloudBees CI Manage License page

.The CloudBees CI Manage License page 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 CloudBees CI system in the selected period.

  • The user has committed changes to the SCM 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.

XML
Json
CSV
<responses version=“2.3” dispatchId=“10454" nodeId=“10.30.176.10”>
  <response requestId=“1" nodeId=“10.30.176.10”>
    <result>
      <lastLogin>1628514816407.00</lastLogin>
      <loginsCount>0.00</loginsCount>
      <verified_label>false</verified_label>
      <lastLogin_label>2021-08-09T13:13:36.407Z</lastLogin_label>
      <verified>0</verified>
      <id>efda06dc-6e0b-3345-b27f-e9fd6cd6c142</id>
      <category>scm</category>
      <email>t.user@gmail.com</email>
      <status>success</status>
      <username>t.user</username>
      <fullUserName />
      <primaryEmail />
    </result>
    ...
    <result>
      <lastLogin>1628516001897.00</lastLogin>
      <loginsCount>0.00</loginsCount>
      <verified_label>false</verified_label>
      <lastLogin_label>2021-08-09T13:33:21.897Z</lastLogin_label>
      <verified>0</verified>
      <id>3f485b55-965c-3adf-bd04-1029634e30ac</id>
      <category>scm</category>
      <email>newrandomtestemail@cb.com</email>
      <status>success</status>
      <username>newrandomtestemail</username>
      <fullUserName />
      <primaryEmail />
    </result>
  </response>
</responses>
{
   "result" : [
      {
         "lastLogin":"1628514816407.00",
         "loginsCount":"0.00",
         "verified_label":"false",
         "lastLogin_label":"2021-08-09T13:13:36.407Z",
         "verified":"0",
         "id":"efda06dc-6e0b-3345-b27f-e9fd6cd6c142",
         "category":"scm",
         "email":"t.user@gmail.com",
         "status":"success",
         "username":"t.user",
         "fullUserName":"",
         "primaryEmail":""
      },
      {
         "lastLogin":"1628515989460.00",
         "loginsCount":"2.00",
         "verified_label":"true",
         "lastLogin_label":"2021-08-09T13:33:09.460Z",
         "verified":"1",
         "id":"ebf90edb-5809-f109-860c-42010a1eb00a",
         "category":"scm",
         "email":"t.user@cb-test.com,dasdasda@cb.test,testuser@cb-test.com",
         "status":"success",
         "username":"testUser",
         "fullUserName":"test user 1",
         "primaryEmail":"testuser@cb-test.com"
      },
   ]
}
lastLogin,loginsCount,verified_label,lastLogin_label,verified,id,category,email,status,username,fullUserName,primaryEmail

1628514816407.00,0.00,false,2021-08-09T13:13:36.407Z,0,\"efda06dc-6e0b-3345-b27f-e9fd6cd6c142\",scm,t.user@gmail.com,success,t.user,,

1628515989460.00,2.00,true,2021-08-09T13:33:09.460Z,1,\"ebf90edb-5809-f109-860c-42010a1eb00a\",scm,\"t.user@cb-test.com,dasdasda@cb.test,testuser@cb-test.com\",success,testUser,\"test user 1\",testuser@cb-test.com
Confirmation from the Jenkins Users dashboard

.The Jenkins User dashboard confirms two active users.

Additional API interfaces

These reports can also be accessed via API by these additional CloudBees CD/RO API inferfaces: