Submitting Evidence
This tutorial demonstrates how to retrieve tests that have evidence due, complete the test, and submit the evidence using the TrustCloud API.
Retrieving an API Key
To make requests to the TrustCloud API, an API key is required. To obtain an API key, please contact support, and follow the instructions in the Getting Started Guide to connect to the API.
Setting up the Request
Before we make any requests, we need to set up our HTTP headers. We need to include the API key in the “Authorization” header, and set the “x-trustcloud-api-version” header to 1 to ensure we are using the correct API version.
Here is an example of the headers we need to include in our HTTP request:
const headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
};
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
HttpGet request = new HttpGet("https://api.trustcloud.ai/tests");
request.setHeader("Authorization", "");
request.setHeader("x-trustcloud-api-version", "1");
using RestSharp;
using RestSharp.Authenticators;
using System;
using System.Collections.Generic;
string apiKey = "";
string apiVersion = "1";
string baseUrl = "https://api.trustcloud.ai";
import requests
headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
}
package main
import (
"encoding/json"
"fmt"
"net/http"
)
apiKey := ""
url := "https://api.trustcloud.ai/v1/tests"
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
GET /controls HTTP/1.1
Host: api.trustcloud.ai
Authorization: Bearer
x-trustcloud-api-version: 1
Retrieve tests with evidence due
To retrieve a list of tests with evidence due, query the /tests API to retrieve a list of tests. The /tests API includes a number of query filter options that you can use:
- name: The name of the test
- evidenceStatus: The status of evidence requirements for this test. Options are:
- missing: Required evidence has not been provided
- due: Evidence required is due
- outdated: Evidence is past-due
- up_to_date: All evidence is up to date for this test
- not_required: Evidence is not required for this test
- testStatus: The current status of the test
- available: The test is not executing, and is available to view or execute
- in_progress: The test is currently executing
- excluded: The test has been excluded from the program. No evidence or test execution is required.
- evidenceDueByDate: All tests with evidence that is pending and due before the specified date (yyyy-mm-dd format).
- EvidenceDueByDays: All tests with evidence that is pending and due in the next x days.
In this example, we will query all tests with an evidence status of due.
const axios = require('axios');
const apiKey = '';
const url = 'https://api.trustcloud.ai/tests?evidenceStatus=due';
axios.get(url, {
headers: {
'Authorization': apiKey,
'x-trustcloud-api-version': '1'
}
}).then(response => {
console.log(response.data);
}).catch(error => {
console.error(error);
});
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
public class TrustCloud {
public static void main(String[] args) throws IOException {
String apiKey = "";
URL url = new URL("https://api.trustcloud.ai/tests?evidenceStatus=due");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("GET");
connection.setRequestProperty("Authorization", apiKey);
connection.setRequestProperty("x-trustcloud-api-version", "1");
Scanner scanner = new Scanner(connection.getInputStream());
while (scanner.hasNext()) {
System.out.println(scanner.nextLine());
}
scanner.close();
}
}
using System;
using System.Net.Http;
using System.Threading.Tasks;
class TrustCloud {
static async Task Main(string[] args) {
string apiKey = "";
string url = "https://api.trustcloud.ai/tests?evidenceStatus=due";
using (HttpClient client = new HttpClient()) {
client.DefaultRequestHeaders.Add("Authorization", apiKey);
client.DefaultRequestHeaders.Add("x-trustcloud-api-version", "1");
HttpResponseMessage response = await client.GetAsync(url);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
}
import requests
api_key = ''
url = 'https://api.trustcloud.ai/tests?evidenceStatus=due'
headers = {
'Authorization': api_key,
'x-trustcloud-api-version': '1'
}
response = requests.get(url, headers=headers)
print(response.json())
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiKey := ""
url := "https://api.trustcloud.ai/tests?evidenceStatus=due"
client := &http.Client{}
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", apiKey)
req.Header.Add("x-trustcloud-api-version", "1")
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error:", err)
return
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
GET /tests?evidenceStatus=due HTTP/1.1
Host: api.trustcloud.ai
Authorization:
x-trustcloud-api-version: 1
Here is an example of the response we might receive:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1234
[
{
"id": "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f",
"testId": "change-management",
"type": "self_assessment",
"name": "Change management workflow",
"level": "basic",
"question": "Do you have a documented change management process outlining the workflow for propagating application and infrastructure code changes to production environments, including tracking, testing, review, and approval?",
"recommendation": "Document your change management process, outlining the workflow for propagating application and infrastructure code changes to the production environment. Including information about tracking, testing, review, and approval processes.",
"evidenceCount": {},
"evidenceDescription": "Your change management, release management, or software development life cycle process documentation, outlining the workflows for propagating application and infrastructure code changes to production environments, including tracking, testing, review and approval",
"evidenceStatus": "missing",
"executionOutcome": {},
"executionSatus": {},
"nextEvidenceDueDate": {},
"owner": {
"name": {},
"id": {}
},
"control": {
"id": "cd2d4fe0-187f-4126-9cdb-edb9867b8040",
"controlId": "PDP-11",
"name": "Product Delivery Process",
"category": "Change Management Workflow"
},
"system": {
"id": {},
"name": {}
},
"metadata": {
"createdby": "59246246-ed25-48a8-ae5e-67732c6ee332",
"createddate": "2022-02-15 17:14:28.757+00",
"lastmodifiedby": "0ef2f025-46df-47d0-8bcd-11f62aa10612",
"lastmodifieddate": "2023-02-20 16:16:07.316+00"
},
},...
]
Submitting a link as evidence
You can submit a link as evidence by invoking the POST /tests/{id}/evidence with a type of “link” and passing the URL in the request body.
const axios = require('axios');
const apiKey = '';
const testId = 'c6354cde-3a4e-4b35-8bfd-aafb33a9f44f';
const url = `https://api.trustcloud.ai/tests/${testId}/evidence`;
const data = {
type: 'link',
url: 'https://someurl.com',
description: 'Some URL evidence to support my test.',
evidenceDate: '2022/12/31'
};
axios.post(url, data, {
headers: {
'Authorization': apiKey,
'Content-Type': 'application/json',
'x-trustcloud-api-version': '1'
}
}).then(response => {
console.log(response.data);
}).catch(error => {
console.error(error);
});
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
public class TrustCloudLink {
public static void main(String[] args) throws IOException {
String apiKey = "";
String testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
String url = "https://api.trustcloud.ai/tests/" + testId + "/evidence";
OkHttpClient client = new OkHttpClient();
String json = "{\"type\":\"link\",\"url\":\"https://someurl.com\",\"description\":\"Some URL evidence to support my test.\",\"evidenceDate\":\"2022/12/31\"}";
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
RequestBody requestBody = RequestBody.create(json, JSON);
Request request = new Request.Builder()
.url(url)
.post(requestBody)
.addHeader("Authorization", apiKey)
.addHeader("x-trustcloud-api-version", "1")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
}
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class TrustCloudLink
{
static async Task Main()
{
string apiKey = "";
string testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
string url = $"https://api.trustcloud.ai/tests/{testId}/evidence";
using HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
client.DefaultRequestHeaders.Add("x-trustcloud-api-version", "1");
string json = "{\"type\":\"link\",\"url\":\"https://someurl.com\",\"description\":\"Some URL evidence to support my test.\",\"evidenceDate\":\"2022/12/31\"}";
HttpContent content = new StringContent(json, Encoding.UTF8, "application/json");
HttpResponseMessage response = await client.PostAsync(url, content);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
import requests
api_key = ""
test_id = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url = f"https://api.trustcloud.ai/tests/{test_id}/evidence"
headers = {
"Authorization": api_key,
"Content-Type": "application/json",
"x-trustcloud-api-version": "1"
}
data = {
"type": "link",
"url": "https://someurl.com",
"description": "Some URL evidence to support my test.",
"evidenceDate": "2022/12/31"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
type EvidenceLink struct {
Type string `json:"type"`
URL string `json:"url"`
Description string `json:"description"`
EvidenceDate string `json:"evidenceDate"`
}
func main() {
apiKey := ""
testID := "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url := "https://api.trustcloud.ai/tests/" + testID + "/evidence"
data := EvidenceLink{
Type: "link",
URL: "https://someurl.com",
Description: "Some URL evidence to support my test.",
EvidenceDate: "2022/12/31",
}
jsonData, err := json.Marshal(data)
if err != nil {
panic(err)
}
client := &http.Client{}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-trustcloud-api-version", "1")
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/evidence HTTP/1.1
Host: api.trustcloud.ai
Authorization:
Content-Type: application/json
x-trustcloud-api-version: 1
{
"type": "link",
"url": "https://someurl.com",
"description": "Some URL evidence to support my test.",
"evidenceDate": "2022/12/31"
}
Submitting a file as evidence
You can submit a file as evidence submitting by invoking the POST /tests/{id}/evidence with a type of “file” and passing the filename in the request body. Files are submitted via multipart form post, with the metadata
const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');
const apiKey = '';
const testId = 'c6354cde-3a4e-4b35-8bfd-aafb33a9f44f';
const url = `https://api.trustcloud.ai/tests/${testId}/evidence`;
const formData = new FormData();
formData.append('description', 'Some file to support my test.');
formData.append('evidenceDate', '2022/12/31');
formData.append('type', 'file');
formData.append('file', fs.createReadStream('evidence.png'), 'evidence.png');
axios.post(url, formData, {
headers: {
...formData.getHeaders(),
'Authorization': apiKey,
'x-trustcloud-api-version': '1'
}
}).then(response => {
console.log(response.data);
}).catch(error => {
console.error(error);
});
import java.io.File;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.MultipartBody;
import okhttp3.OkHttpClient;
import okhttp3.RequestBody;
import okhttp3.Request;
import okhttp3.Response;
public class TrustCloudFile {
public static void main(String[] args) throws IOException {
String apiKey = "";
String testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
String url = "https://api.trustcloud.ai/tests/" + testId + "/evidence";
String filePath = "evidence.png";
OkHttpClient client = new OkHttpClient();
File file = new File(filePath);
MediaType mediaType = MediaType.parse("image/png");
RequestBody fileBody = RequestBody.create(file, mediaType);
RequestBody requestBody = new MultipartBody.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("description", "Some file to support my test.")
.addFormDataPart("evidenceDate", "2022/12/31")
.addFormDataPart("type", "file")
.addFormDataPart("file", "evidence.png", fileBody)
.build();
Request request = new Request.Builder()
.url(url)
.post(requestBody)
.addHeader("Authorization", apiKey)
.addHeader("x-trustcloud-api-version", "1")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
}
}
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
class TrustCloudFile
{
static async Task Main()
{
string apiKey = "";
string testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
string url = $"https://api.trustcloud.ai/tests/{testId}/evidence";
string filePath = "evidence.png";
using HttpClient client = new HttpClient();
using MultipartFormDataContent formData = new MultipartFormDataContent();
formData.Add(new StringContent("Some file to support my test."), "description");
formData.Add(new StringContent("2022/12/31"), "evidenceDate");
formData.Add(new StringContent("file"), "type");
formData.Add(new StreamContent(File.OpenRead(filePath)), "file", "evidence.png");
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
client.DefaultRequestHeaders.Add("x-trustcloud-api-version", "1");
HttpResponseMessage response = await client.PostAsync(url, formData);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
import requests
api_key = ""
test_id = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url = f"https://api.trustcloud.ai/tests/{test_id}/evidence"
headers = {
"Authorization": api_key,
"x-trustcloud-api-version": "1"
}
data = {
"description": "Some file to support my test.",
"evidenceDate": "2022/12/31",
"type": "file"
}
with open("evidence.png", "rb") as file:
files = {"file": ("evidence.png", file, "image/png")}
response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
)
func main() {
apiKey := ""
testID := "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url := "https://api.trustcloud.ai/tests/" + testID + "/evidence"
var buffer bytes.Buffer
writer := multipart.NewWriter(&buffer)
description, _ := writer.CreateFormField("description")
io.WriteString(description, "Some file to support my test.")
evidenceDate, _ := writer.CreateFormField("evidenceDate")
io.WriteString(evidenceDate, "2022/12/31")
evidenceType, _ := writer.CreateFormField("type")
io.WriteString(evidenceType, "file")
file, err := os.Open("evidence.png")
if err != nil {
fmt.Println(err)
return
}
defer file.Close()
fileWriter, _ := writer.CreateFormFile("file", "evidence.png")
io.Copy(fileWriter, file)
writer.Close()
req, _ := http.NewRequest("POST", url, &buffer)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
var respBuffer bytes.Buffer
io.Copy(&respBuffer, resp.Body)
fmt.Println(respBuffer.String())
}
POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/evidence HTTP/1.1
Host: api.trustcloud.ai
Authorization:
Content-Type: multipart/form-data; boundary=
x-trustcloud-api-version: 1
--
Content-Disposition: form-data; name="description"
Some file to support my test.
--
Content-Disposition: form-data; name="evidenceDate"
2022/12/31
--
Content-Disposition: form-data; name="type"
file
--
Content-Disposition: form-data; name="file"; filename="evidence.png"
Content-Type:
----
Completing the test
Once you submit evidence associated with a test, you can complete the test by invoking POST /tests/{id}/execute and answering the assessment with either a yes (to pass the assessment) or no to fail the assessment. .
const axios = require('axios');
const apiKey = '';
const testId = 'c6354cde-3a4e-4b35-8bfd-aafb33a9f44f';
const url = `https://api.trustcloud.ai/tests/${testId}/execute`;
const data = {
answer: yes,
comment: “Optional description of the assessment details”
};
axios.post(url, data, {
headers: {
'Authorization': apiKey,
'Content-Type': 'application/json',
'x-trustcloud-api-version': '1'
}
}).then(response => {
console.log(response.data);
}).catch(error => {
console.error(error);
});
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
public class TrustCloudLink {
public static void main(String[] args) throws IOException {
String apiKey = "";
String testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
String url = "https://api.trustcloud.ai/tests/" + testId + "/execute";
OkHttpClient client = new OkHttpClient();
String json = "{\"answer\":\"yes\",\"comment\":\"Optional description of the assessment details\"}";
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
RequestBody requestBody = RequestBody.create(json, JSON);
Request request = new Request.Builder()
.url(url)
.post(requestBody)
.addHeader("Authorization", apiKey)
.addHeader("x-trustcloud-api-version", "1")
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
}
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class TrustCloudLink
{
static async Task Main()
{
string apiKey = "";
string testId = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f";
string url = $"https://api.trustcloud.ai/tests/{testId}/execute";
using HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
client.DefaultRequestHeaders.Add("x-trustcloud-api-version", "1");
string json = "{\"answer\":\"yes\",\"comment\":\"Optional description of the assessment details\"}";
HttpContent content = new StringContent(json, Encoding.UTF8, "application/json");
HttpResponseMessage response = await client.PostAsync(url, content);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
import requests
api_key = ""
test_id = "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url = f"https://api.trustcloud.ai/tests/{test_id}/evidence"
headers = {
"Authorization": api_key,
"Content-Type": "application/json",
"x-trustcloud-api-version": "1"
}
data = {
"answer": "yes",
"comment": "Optional description of the assessment details"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
type EvidenceLink struct {
Type string `json:"type"`
URL string `json:"url"`
Description string `json:"description"`
EvidenceDate string `json:"evidenceDate"`
}
func main() {
apiKey := ""
testID := "c6354cde-3a4e-4b35-8bfd-aafb33a9f44f"
url := "https://api.trustcloud.ai/tests/" + testID + "/execute"
data := EvidenceLink{
answer: "yes",
comment: "Optional description of the assessment details"
"
}
jsonData, err := json.Marshal(data)
if err != nil {
panic(err)
}
client := &http.Client{}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-trustcloud-api-version", "1")
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}
POST /tests/c6354cde-3a4e-4b35-8bfd-aafb33a9f44f/execute HTTP/1.1
Host: api.trustcloud.ai
Authorization:
Content-Type: application/json
x-trustcloud-api-version: 1
{
"answer": "yes",
"comment": "Optional description of the assessment details"
}