This set of APIs generates reports asynchronously. There are three API’s, one for the organization, one for products and one for individual projects.
generateOrganizationReportAsync
generateProductReportAsync
generateProjectReportAsync
The type of report to be generated is set with the reportType parameter in each API.
Additional parameters available with some of the reportTypes can be included in the API request by using the optional filter parameter, as shown in the examples.
generateOrganizationReportAsync
Parameter | Description | Type | Required |
requestType | generateOrganizationReportAsync | string | Yes |
orgToken | API key which is a unique identifier of the organization. | string | Yes |
userKey | The ID of the user’s profile, which uniquely identifies the user in WhiteSource. | string | Yes |
reportType | OrgHistoryReport, OrgInventoryReport, OrgLicensesReport, OrgSourceFileInventoryReport, OrgClusterInventoryReport, OrgAlertsReport, OrgIgnoreAlertsReport, OrgResolvedAlertsReport, OrgSecurityAlertsReport, OrgLibrarySecurityAlertsReport, OrgVulnerabilityReport, OrgContainerVulnerabilityReport, OrgBugsReport, OrgMembersReport, OrgAttributesReport, OrgEffectiveLicensesReport, RiskReport, OrgInHouseReport, OrgLibraryLocationReport, PluginPolicyViolationReport, PluginRequestHistoryReport, ChangeLogReport, OrgLicenseAndComplianceAlertReport, OrgEarlyWarningsAlertReport, OrgEarlyWarningsReport | string | Yes |
format | json, xlsx, pdf | string | Yes |
filter | Any additional parameters, as listed individually for each reportType on the synchronous reports page | object | No |
Request Example
{
"requestType" : "generateOrganizationReportAsync",
"orgToken" : "organization_api_key",
"userKey": "user_key",
"reportType": "OrgLibrarySecurityAlertsReport"
"format" : "json",
"filter" : {
"status": “active”
}
}
|
Response
{
"asyncProcessStatus": {
"uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
"requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
"contextId": "244934",
"contectType": "DOMAIN",
"processType": "DOMAIN_VULNERABILITIES",
"userEmail": "adam.smith@whitesourcesoftware.com",
"messageContentSha1": "b480c892e59a2f05954ce727bd3f2a4e882f9e13",
"status": "PENDING",
"created": "2022-4-15 11:45:20",
"modified": "2022-4-15 11:45:20",
}
}
generateProductReportAsync
PARAMETERS
Parameter | Description | Type | Required |
requestType | generateProductReportAsync | string | Yes |
orgToken | API key which is a unique identifier of the organization. | string | Yes |
userKey | The ID of the user’s profile, which uniquely identifies the user in WhiteSource. | string | Yes |
reportType | ProductHistoryReport, ProductInventoryReport, ProductLicenseCompatibilityReport, ProductLicensesReport, ProductSourceFileInventoryReport, ProductClusterInventoryReport, ProductAlertsReport, ProductIgnoreAlertsReport, ProductResolvedAlertsReport, ProductSecurityAlertsReport, ProductLibrarySecurityAlertsReport, ProductVulnerabilityReport, ProductContainerVulnerabilityReport, ProductBugsReport, ProductMembersReport, ProductAttributesReport, ProductEffectiveLicensesReport, ProductDiffReport, ProductRiskReport, ProductAttributionReport, ProductInHouseReport, ProductLibraryLocationReport, ProductLicenseAndComplianceAlertReport, ProductEarlyWarningsAlertReport, ProductEarlyWarningsReport | string | Yes |
format | json, xlsx, pdf | string | Yes |
filter | Any additional parameters, as listed individually for each reportType on the synchronous reports page | object | No |
Request Example
{
"requestType" : "generateOrganizationReportAsync",
"orgToken" : "organization_api_key",
"userKey": "user_key",
"reportType": "ProductAttributesReport"
"format" : "xlsx",
"filter" : {
"reportingScope": “licenses”,
"reportingAggregationMode": "BY_PROJECT"
}
}
|
Response
{
"asyncProcessStatus": {
"uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
"requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
"contextId": "244934",
"contectType": "DOMAIN",
"processType": "DOMAIN_VULNERABILITIES",
"userEmail": "adam.smith@whitesourcesoftware.com",
"messageContentSha1": "b480c892e59a2f05954ce727bd3f2a4e882f9e13",
"status": "PENDING",
"created": "2022-4-15 11:45:20",
"modified": "2022-4-15 11:45:20",
}
}
generateProjectReportAsync
Parameter | Description | Type | Required |
requestType | generateProjectReportAsync | string | Yes |
orgToken | API key which is a unique identifier of the organization. | string | Yes |
userKey | The ID of the user’s profile, which uniquely identifies the user in WhiteSource. | string | Yes |
reportType | ProjectHistoryReport, ProjectInventoryReport, ProjectLicenseCompatibilityReport, ProjectLicensesReport, ProjectSourceFileInventoryReport, ProductClusterInventoryReport, ProjectAlertsReport, ProjectIgnoreAlertsReport, ProjectResolvedAlertsReport, ProjectSecurityAlertsReport, ProjectLibrarySecurityAlertsReport, ProjectVulnerabilityReport, ProjectContainerVulnerabilityReport, ProjectBugsReport, ProjectMembersReport, ProjectAttributesReport, ProjectDiffReport, RiskReport, AttributionReport, ProjectInHouseReport, ProjectLibraryLocationReport, ProjectLicenseAndComplianceAlertReport, ProjectEarlyWarningsAlertReport, ProjectEarlyWarningsReport | string | Yes |
format | json, xlsx, pdf | string | Yes |
filter | Any additional parameters, as listed individually for each reportType on the synchronous reports page | object | No |
Request Example
{
"requestType" : "generateOrganizationReportAsync",
"orgToken" : "organization_api_key",
"userKey": "user_key",
"reportType": "ProjectAttributesReport"
"format" : "pdf",
"filter" : {
"reportingScope": “summary”,
"includeVersions": "true"
}
}
|
Response
{
"asyncProcessStatus": {
"uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
"requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
"contextId": "244934",
"contectType": "DOMAIN",
"processType": "DOMAIN_VULNERABILITIES",
"userEmail": "adam.smith@whitesourcesoftware.com",
"messageContentSha1": "b480c892e59a2f05954ce727bd3f2a4e882f9e13",
"status": "PENDING",
"created": "2022-4-15 11:45:20",
"modified": "2022-4-15 11:45:20",
}
}
The status of the requested report is checked using the getAsyncProcessStatus. The {{status}} parameter will contain one of four values:
PENDING
IN_PROGRESS
FAILED
SUCCESS
getAsyncProcessStatus
Parameter | Description | Type | Required |
requestType | getAsyncProcessStatus | string | Yes |
orgToken | API key which is a unique identifier of the organization. | string | Yes |
userKey | The ID of the user’s profile, which uniquely identifies the user in WhiteSource. | string | Yes |
uuid | The UUID returned in the response from one of the “GenerateXXReportAsync” APIs | string | Yes |
Request Example
{
"requestType" : "getAsyncProcessStatus",
"orgToken" : "organization_api_key",
"userKey": "user_key",
"uuid": "36466e69-bda1-43d3-9962-6f3a341720b9"
}
}
|
Response
{
"asyncProcessStatus": {
"uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
"requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
"contextId": "244934",
"contectType": "DOMAIN",
"processType": "DOMAIN_VULNERABILITIES",
"userEmail": "adam.smith@whitesourcesoftware.com",
"messageContentSha1": "b480c892e59a2f05954ce727bd3f2a4e882f9e13",
"status": "SUCCESS",
"created": "2022-4-15 11:45:20",
"modified": "2022-4-15 11:45:20",
}
}
Once SUCCESS is returned by getAsyncProcessStatus, the report is ready for download using downloadAsyncReport.
downloadAsyncReport
Parameter | Description | Type | Required |
requestType | downloadAsyncReport | string | Yes |
orgToken | API key which is a unique identifier of the organization. | string | Yes |
userKey | The ID of the user’s profile, which uniquely identifies the user in WhiteSource. | string | Yes |
reportStatusUUID | The UUID returned in the response from one of the “GenerateXXReportAsync” APIs | string | Yes |
Request Example
{
"requestType" : "downloadAsyncReport",
"orgToken" : {{orgToken}},
"userKey" : {{userKey}},
"reportStatusUUID" :{{asyncProcessStatus.uuid}}
}