Promote Scan REST API - v2

The Promote Scan REST API allows for an existing scan report to be promoted to a specified stage. The scan metadata generated for a specific build scan can be resubmitted for an evaluation of its components without having to rebuild the application. This new evaluation will update the most recent security and license data against your current policies.

By default, only the most recent scan files are retained by IQ Server and can be promoted. Unless this default is changed, all older scan files will be automatically purged when a new scan occurs so they cannot be used for promotion.

Use the Configuration REST API to retain scan files for a longer period of time.

Set the purgeScanFiles property to withReports.

Example: curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"purgeScanFiles": "withReports"}' http://localhost:8070/api/v2/config

The API uses the following REST methods

  • POST - to submit a request to promote a scan to another stage.
  • GET - to check the status of a promote scan request.

Promotion Workflow

  1. Get the Application Internal ID
  2. Choose the 

Step 1 - Get the Application Internal ID

The application's internal ID is required as a path parameter for the promote request. This can be found using the application public ID, which can be seen next to the application name in the IQ Server GUI after selecting the application on the Organization & Policies tab.

Once you have the application's public ID, you can use the following GET REST resource from our Application API to get the application's internal ID.

GET /api/v2/applications?publicId={applicationPublicId}

Using the cURL command, it would look like this

curl -u admin:admin123 'http://localhost:8070/api/v2/applications?publicId=MyApplicationPublicID'

and would result in a JSON response like this

{
	"applications": [{
		"id": "cb748fb6ff8f4251b40b63edf1cc465c",
		"publicId": "MyApplicationPublicID",
		"name": "MyApplication",
		"organizationId": "81ae1fc7875441f2bec28d78d0f467ec",
		"contactUserName": null,
		"applicationTags": []
	}]
}

where the "id" is the application's internal ID.

Step 2 - Choose the Source

The promote scan request body requires either the scan ID for a specific stage or a source stage ID.

Using the Scan ID (Option 1)

You may find the Scan ID from the scan output when using any of the integrations as well as from the Report-related REST APIs.

Using the Source Stage ID (Option 2)

When using the source stage ID, the latest scan for the application will be used.  Using the same stage for both the source and target will resubmit the latest scan report for updated information.  The source stage ID can be one of the following:

  • build
  • stage-release
  • release
  • operate

Step 3 - Choose a Target Stage ID

The promote scan request body also requires the target stage ID for the scan to be promoted to. This will typically take one of the same values available to the source stage ID in step 2. Your choice will probably depend on how you are using the different stages, for which we offer some usage suggestions.

Step 4 - Submit a Promote Scan Request

At this point, we should have the following

  • An internal application ID (from step 1)
  • A scan ID OR a source stage ID (from step 2)
  • A desired target stage ID (from step 3)

which we can use to create our request. We will send this request to the following POST REST resource

POST /api/v2/evaluation/applications/{applicationInternalId}/promoteScan

with one of the following JSON bodies

{
	"scanId": "896791eb6a484d51bb570dca94dc2c67",
	"targetStageId": "stage-release"
}
{
	"sourceStageId": "build",
	"targetStageId": "stage-release"
}

Using the cURL command, it would look like one of these

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"scanId":"896791eb6a484d51bb570dca94dc2c67","targetStageId":"stage-release"}' 'http://localhost:8070/api/v2/evaluation/applications/cb748fb6ff8f4251b40b63edf1cc465c/promoteScan'
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"sourceStageId":"build","targetStageId":"stage-release"}' 'http://localhost:8070/api/v2/evaluation/applications/cb748fb6ff8f4251b40b63edf1cc465c/promoteScan'

and result in a JSON response like this

{
	"statusUrl": "api/v2/evaluation/applications/cb748fb6ff8f4251b40b63edf1cc465c/status/accc369749774924baa1d207494c29e1"
}

Step 5 - Check the Status

The status URL returned in step 4 can be used to check the scan promotion status, which can be one of the following

  • "PENDING"
  • "FAILED"
  • "COMPLETED"

To get this, we will send a request to the following GET REST resource

GET api/v2/evaluation/applications/{applicationInternalId}/status/{statusId}

Using the cURL command, it would look like this

curl -u admin:admin123 'http://localhost:8070/api/v2/evaluation/applications/cb748fb6ff8f4251b40b63edf1cc465c/status/accc369749774924baa1d207494c29e1'

and result in a JSON response like this if the scan promotion is pending (still in progress)

{
	"status": "PENDING"
}

or a JSON response like this with a reason message if, in a rare case, the scan promotion failed

{
	"status": "FAILED",
	"reason": "message"
}

or a JSON response like this with report links if the scan promotion completed

{
	"status": "COMPLETED",
	"reportHtmlUrl": "ui/links/application/cb748fb6ff8f4251b40b63edf1cc465c/report/affdb6b964a64f0bad2db7170c7560dc",
	"embeddableReportHtmlUrl": "ui/links/application/cb748fb6ff8f4251b40b63edf1cc465c/report/affdb6b964a64f0bad2db7170c7560dc/embeddable",
	"reportPdfUrl": "ui/links/application/cb748fb6ff8f4251b40b63edf1cc465c/report/affdb6b964a64f0bad2db7170c7560dc/pdf",
	"reportDataUrl": "api/v2/applications/cb748fb6ff8f4251b40b63edf1cc465c/reports/affdb6b964a64f0bad2db7170c7560dc"
}

Finally, when the status URL indicates a completed scan promotion status, then the various reports can be viewed via the provided links.