Promote Scan REST API - v2

The Promote Scan REST API, for IQ Server Release 51 and above, allows an existing scan data file to be promoted to a given stage. This means that it will be evaluated at the current point in time at the specified stage. This evaluation will use the most recent security and license data as well as your current policies against the snapshot of the application that the scan data file represents.

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.

For the API we provide a step-by-step example using the HTTP client cURL, though any HTTP client tool could be used. In addition, we reference other APIs as necessary.

Step 1 - Get the Application Internal ID

The promote scan request URL requires the application internal ID as a path parameter. 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 public ID, you can use the following GET REST resource from our application API to get the application 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 internal ID.

Step 2 - Choose the Scan ID or the Source Stage ID

The promote scan request body requires either the latest scan ID for a specific stage or a source stage ID. In the latter case, the latest scan for the application and stage represented by the given application internal ID and source stage ID will be used. Note that the application internal ID is supplied in the request URL as a path parameter.

If you don't have the latest scan ID for a specific stage, then it may be easier to supply the source stage ID, which is typically 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 promote scan 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.