Skip to main content

Evidence collection

Evidence collection can be performed at the framework, requirement, or control level. In order to complete the process, three actions must be taken in sequential order:

  1. Kick off an EvidenceCollectionJob via API
  2. Poll for the completion of the EvidenceCollectionJob
  3. Use the completed EvidenceCollectionJob to receive an AWS s3 link to download its output

Start an EvidenceCollectionJob via API​

Each object type has a different GraphQL mutation to call to start its EvidenceCollectionJob. Ensure to use the correct mutation for the specified object type.

Start Framework EvidenceCollectionJob​

Variables​
  • input: StartEvidenceCollectionJobForFrameworkItemInput
    • frameworkId: The indentifier of the framework for which to start an EvidenceCollectionJob.
Mutation​
  mutation startEvidenceCollectionJobforFramework(
    $input: StartEvidenceCollectionJobForFrameworkInput!
  ) {
    startEvidenceCollectionJobforFramework(input: $input) {
      id
      accountId
      userId
      frameworkId
      frameworkItemId
      libraryItemId
      status
      progress
      createTimestamp
      endTimestamp
    }
  }

Start Control EvidenceCollectionJob​

Variables​
  • input: StartEvidenceCollectionJobForLibraryItemInput
    • libraryItemId: The identifier of the library item for which to start an EvidenceCollectionJob (e.g., Control).
Mutation​
mutation startEvidenceCollectionJobforLibraryItem(
  $input: StartEvidenceCollectionJobForLibraryItemInput!
) {
  startEvidenceCollectionJobforLibraryItem(input: $input) {
    id
    accountId
    userId
    frameworkId
    frameworkItemId
    libraryItemId
    status
    progress
    createTimestamp
    endTimestamp
  }
}

Poll for EvidenceCollectionJob completion​

When a job has completed, its status field is set to COMPLETED.

Variables​
  • input: EvidenceCollectionJobInput
    • id: The identifier of the EvidenceCollectionJob to fetch.
Query​
query evidenceCollectionJob($input: EvidenceCollectionJobInput!) {
    evidenceCollectionJob(input: $input) {
      id
      accountId
      userId
      frameworkId
      frameworkItemId
      libraryItemId
      status
      progress
      createTimestamp
      endTimestamp
    }
  }

The returned link property is an AWS S3 Presigned URL that contains the zipped evidence file to download. This URL will be valid for 2 hours. To generate a new URL (if the timeout is reached), just call the same query below again.

Variables​
  • input: DownloadLinkForEvidenceCollectionJobInput
    • evidenceCollectionJobId: The identifier of the EvidenceCollectionJob for which to retrieve a download link.
Query​
query downloadLinkForEvidenceCollectionJob(
  $input: DownloadLinkForEvidenceCollectionJobInput!
) {
  downloadLinkForEvidenceCollectionJob(input: $input) {
    link
  }
}

Contents