Reports API (Asynchronous)

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

1 2 3 4 5 6 7 8 9 10 {     "requestType" : "generateOrganizationReportAsync", "orgToken" : "organization_api_key",     "userKey": "user_key", "reportType": "OrgLibrarySecurityAlertsReport"     "format" : "json", "filter" : { "status": “active” } }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "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

1 2 3 4 5 6 7 8 9 10 11 {     "requestType" : "generateOrganizationReportAsync", "orgToken" : "organization_api_key",     "userKey": "user_key", "reportType": "ProductAttributesReport"     "format" : "xlsx", "filter" : { "reportingScope": “licenses”, "reportingAggregationMode": "BY_PROJECT" } }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "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

1 2 3 4 5 6 7 8 9 10 11 {     "requestType" : "generateOrganizationReportAsync", "orgToken" : "organization_api_key",     "userKey": "user_key", "reportType": "ProjectAttributesReport"     "format" : "pdf", "filter" : { "reportingScope": “summary”, "includeVersions": "true" } }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "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 getAsyncProcessStatus. The status parameter will contain one of these 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

1 2 3 4 5 6 7 {     "requestType" : "getAsyncProcessStatus", "orgToken" : "organization_api_key",     "userKey": "user_key", "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9" } }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "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 the status of the report returns SUCCESS, the report is ready for download using the downloadAsyncReport API.

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

1 2 3 4 5 6 { "requestType" : "downloadAsyncReport",   "orgToken" : {{orgToken}},   "userKey" : {{userKey}},   "reportStatusUUID" :{{asyncProcessStatus.uuid}} }