Reports API - Asynchronous

This set of APIs generates reports asynchronously. There are API’s for the organization, products and individual projects.

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.

NOTE: Not only reports can be generated asynchronously. The changeOriginLibrary API request can be generated asynchronously to prevent timeouts in large organizations with many projects.
For details, see Licenses and Libraries API | Change Origin Library.

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 Mend.	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, OrgEffectiveUsageAnalysisReport	string	Yes
format	json, xlsx, xml, pdf (where xlsx is available, it is also the default) Not all formats are available for all report types. Refer to the synchronous counterpart of each report to see which formats are available for it.	string	Yes
filter	Any additional parameters, as listed individually for each reportType on the synchronous reports page	object	No

Request Example

CODE

{
    "requestType" : "generateOrganizationReportAsync",
    "orgToken" : "organization_api_key",
    "userKey": "user_key",
    "reportType": "OrgLibrarySecurityAlertsReport",
    "format" : "json",
    "filter" : {
        "status": “active”
    }
}

Response

CODE

{
    "asyncProcessStatus": {
        "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
        "requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
        "contextId": "244934",
        "contextType": "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
productToken	API key which is a unique identifier of the product.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in Mend.	string	Yes
reportType	ProductHistoryReport, ProductInventoryReport, ProductLicenseCompatibilityReport, ProductLicensesReport, ProductSourceFileInventoryReport, ProductClusterInventoryReport, ProductAlertsReport, ProductIgnoreAlertsReport, ProductResolvedAlertsReport, ProductSecurityAlertsReport, ProductLibrarySecurityAlertsReport, ProductVulnerabilityReport, ProductContainerVulnerabilityReport, ProductBugsReport, ProductMembersReport, ProductAttributesReport, ProductEffectiveLicensesReport, ProductDiffReport, RiskReport, ProductAttributionReport, ProductInHouseReport, ProductLibraryLocationReport, ProductLicenseAndComplianceAlertReport, ProductEarlyWarningsAlertReport, ProductEarlyWarningsReport, ProductSBOMReport	string	Yes
format	json, xlsx, xml, pdf (where xlsx is available, it is also the default) Note: Not all formats are available for all report types. Refer to the synchronous counterpart of each report to see which formats are available for it.	string	Yes
filter	Any additional parameters, as listed individually for each reportType on the synchronous reports page	object	No

Request Example

CODE

{
    "requestType" : "generateProductReportAsync",
    "productToken" : "product_api_key",
    "userKey": "user_key",
    "reportType": "ProductAttributesReport",
    "format" : "xlsx",
    "filter" : {
        "reportingScope": “licenses”,
        "reportingAggregationMode": "BY_PROJECT"
    }
}

Response

CODE

{
    "asyncProcessStatus": {
        "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
        "requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
        "contextId": "244934",
        "contextType": "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
projectToken	API key which is a unique identifier of the project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in Mend.	string	Yes
reportType	ProjectHistoryReport, ProjectInventoryReport, ProjectLicenseCompatibilityReport, ProjectLicensesReport, ProjectSourceFileInventoryReport, ProjectAlertsReport, ProjectIgnoreAlertsReport, ProjectResolvedAlertsReport, ProjectSecurityAlertsReport, ProjectLibrarySecurityAlertsReport, ProjectVulnerabilityReport, ProjectContainerVulnerabilityReport, ProjectBugsReport, ProjectMembersReport, ProjectDiffReport, RiskReport, AttributionReport, ProjectInHouseReport, ProjectLibraryLocationReport, ProjectLicenseAndComplianceAlertReport, ProjectEarlyWarningsAlertReport, ProjectEarlyWarningsReport, ProjectSBOMReport	string	Yes
format	json, xlsx, xml, pdf (where xlsx is available it is also the default) Not all formats are available for all report types. Refer to the synchronous counterpart of each report to see which formats are available for it.	string	Yes
filter	Any additional parameters, as listed individually for each reportType on the synchronous reports page	object	No

Request Example

CODE

{
    "requestType" : "generateProjectReportAsync",
    "projectToken" : "project_api_key",
    "userKey": "user_key",
    "reportType": "ProjectInventoryReport",
    "format" : "pdf",
    "filter" : {
        "reportingScope": “summary”,
        "includeVersions": "true"
    }
}

Response Example

CODE

{
    "asyncProcessStatus": {
        "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
        "requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
        "contextId": "244934",
        "contextType": "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",
    }
}

SBOM Reporting

This is a new report type that collects the various options for SBOM reporting into a single API request based on scope (product or project).

ProductSBOMReport

Parameter	Description	Type	Required
requestType	generateProductReportAsync	string	Yes
projectToken	API key which is a unique identifier of the product..	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in Mend.	string	Yes
reportType	ProductSBOMReport	string	Yes
standard	SPDX (case insensitive) CycloneDX (case insensitive)	string	Yes
version	The SBOM standard version. The available values for SPDX: “2.2” (default) or “2.3”. For CycloneDX “1.4” (default) or “1.5”.	string	No
format	SPDX: XML, YAML, JSON, TV, XLSX (case insensitive), CycloneDX: XML, JSON (case insensitive)	string	Yes
maxDepthLevel	The depth in the dependency tree to include in the report. Where the top level is 0. Note: Only supported by the CycloneDX standard.	number	Default: 0 (top level only)
includeVulnerabilities	A boolean parameter that controls whether or not to include vulnerabilities in the SBOM report.	boolean	No (Default: true)

Request Example

CODE

{
    "requestType": "generateProductReportAsync",
    "productToken": "<productToken>",
    "userKey": "<userKey>",
    "reportType":"ProductSBOMReport",
    "standard":"cyclonedx",
    "includeVulnerabilities":"false",
    "format":"json"
}

Response

The response is the requested report file.

ProjectSBOMReport

Parameter	Description	Type	Required
requestType	generateProjectReportAsync	string	Yes
projectToken	API key which is a unique identifier of the project.	string	Yes
userKey	the ID of the user’s profile, which uniquely identifies the user in Mend.	string	Yes
reportType	ProjectSBOMReport	string	Yes
standard	SPDX (case insensitive) CycloneDX (case insensitive)	string	Yes
version	The SBOM standard version. The available values for SPDX: “2.2” (default) or “2.3”. For CycloneDX “1.4” (default) or “1.5”.	string	No
format	SPDX: XML, YAML, JSON, TV, XLSX (case insensitive), CycloneDX: XML, JSON (case insensitive)	string	Yes
maxDepthLevel	The depth in the dependency tree to include in the report. Where the top level is 0. Note: Only supported by the CycloneDX standard.	number	default: 0 (top level only)
includeVulnerabilities	A boolean parameter that controls whether or not to include vulnerabilities in the SBOM report.	boolean	No (Default: true)

Request Example

CODE

{
    "requestType": "generateProjectReportAsync",
    "projectToken": "<projectToken>",
    "userKey": "<userKey>",
    "reportType":"ProjectSBOMReport",
    "standard":"spdx",
    "format":"json"
}

Response

CODE

{
    "asyncProcessStatus": {
        "uuid": "527cd6d7-74f9-4f3c-9a25-16e01550db86",
        "requestToken": "24460c1f47b544f039804ef039762265d1678743921551",
        "contextId": 1538167,
        "contextType": "PROJECT",
        "processType": "PROJECT_SBOM_REPORT",
        "userEmail": "adam.smith@whitesourcesoftware.com",
        "messageContentSha1": "a830df5dcbee9d36045d9f2ec90496bd31a2cf30",
        "status": "PENDING",
        "created": "2023-03-13 21:45:21",
        "modified": "2023-03-13 21:45:21"
    }
}

getAsyncProcessStatus

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

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 Mend.	string	Yes
uuid	The UUID returned in the response from one of the “GenerateXXReportAsync” APIs	string	Yes

Request Example

CODE

{
    "requestType" : "getAsyncProcessStatus",
    "orgToken" : "organization_api_key",
    "userKey": "user_key",
    "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9"
}

Response

CODE

{
    "asyncProcessStatus": {
        "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
        "requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
        "contextId": "244934",
        "contextType": "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

Note: All of the APIs and their responses in this article have the “uuid” flag as “uuid”, except for downloadAsyncReport, which calls for a “reportStatusUUID” instead of “uuid” value. This value is the same as the “uuid” value, the naming is just different.

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 Mend.	string	Yes
reportStatusUUID	The UUID returned in the response from one of the “GenerateXXReportAsync” APIs	string	Yes

Request Example

CODE

{
  "requestType" : "downloadAsyncReport",
  "orgToken" : {{orgToken}},
  "userKey" : {{userKey}},
  "reportStatusUUID" :{{asyncProcessStatus.uuid}}
}

Response

The response is the requested report file.

Notes:

The report is downloaded as a ZIP file that contains the actual report file.
For very large reports, multiple files will be included in the exported ZIP.