Table of contents
In our Technical Documentation the required information when working with the Testify API is listed.
The Testify API can be used to query information from Testify, but also to create and update information. With help of the Testify API it is easily possible to connect Testify to your own systems and exchange information in an automated way.
The Testify API is a REST API which can be accessed via authenticated HTTP requests (using an API key). The documentation with all available endpoints can be found at https://cloud.testify.io/core/services/swagger/index.html and it is recommended to use the most recent version, which at the moment of writing this documentation is Testify API v2.0. Note that as of now all listed versions are supported, but it is not recommended to use the internal or older APIs as these might get deprecated in the future.
Depending on whether the https://cloud.testify.io/ stage or an own stage is used, the StageBaseUrl can differ and must be adapted in the request URL (and also in the Swagger UI URL). All examples in this documentation use https://cloud.testify.io as StageBaseUrl and assume that the Testify stage is used.
To access the Testify API a Testify user with a valid API key is needed. This API key must then be sent in every requests header.
Please be aware that a user in Testify has roles and permissions and is allowed to make certain requests based on that. An API key is always generated for a certain Testify user and when making a request with an API key the permissions of that user are used. Therefore, it is advised to create an own Interface User that has all roles and permissions needed for accessing the endpoints. |
Go to https://cloud.testify.io/todos and Log In with your regular account.
Go to “Administration” → “Users” and create a new Interface User with a self defined password and all roles assigned.
Within the User’s Profile, click on the context menu and select “Generate API key”.
Note the API key that consists of secret, Subject and Tenant.
Please be aware that this API key can only be viewed once and must be regenerated otherwise. Regenerating means disabling the previous used API key. |
Place secret, Subject and Tenant in request header.
Many entities in Testify namely checklist templates, checklist instances, testobjects, testobject-types testequipments, testequipment-types, customfields, issue categories, groups and users have an external and an internal ID. The internal id must be a globally unique identifier in the format of “00000000-0000-0000-0000-000000000000“, whereas the external id can be in a format more readable for humans to better recognize the object and must also be unique.
E.g. internal id: 9033d3c6-5897-484c-a247-61cc4e636920, external id: my-testobject
Users can choose an external ID to make it easy to correlate the entities to entities in other systems. For example, when testobjects are synced with an ERP system, you could reuse the IDs of the ERP system and set the external IDs in testify with that value. That will make it easy later on to find the correlationg test object for an entity in your ERP system by just doing an ID lookup.
In General, all IDs used by the Testify Public API are external IDs.
An internal ID is always automatically generated by the system itself. The external ID can be chosen when creating the entity via the API by just assigning a value to the ID property. This value has to be unique, though. When creating an object without providing an external ID, it automatically gets set to the value of the generated internal ID.
With  |
A  |
A  |
The If a property is included in the JSON request body, it's value should be updated with the value from the JSON. All other properties that are not included will stay the same as before. To delete an optional property value this can be done by setting the property in the JSON to NULL. For properties that contain lists, NULL and an empty array both will mean the list will be emptied after the update. If you want to update a list you have to provide the complete list of entries again that should be set after the update operation.  |
Webhooks allow you to respond on events that occur in Testify in an automated way, without the need to make requests repeatedly. To use webhooks a HTTP server where Testify is allowed to send POST requests is needed. When this is available, it can be easily configured within Testify on what events should be reacted to and to which URL the request should be sent to.
As logged in User go to “Administration” → “Workflows” and create a new Workflow.
Define a Name.
Define an Event.
Define an Action with scope “Webhook” and type “trigger”.
Click on “Parameters” and provide the URL of the webhook that should be called and can be accessed by Testify via POST request. As an optional parameter, an Identifier can be specified, which then will be sent in the request body. Also, the request timeout and the HTTP status codes that indicate success can be customized, as well as some authorization options containing of a secret and HTTP headers. Please consider that Content-Type: application/json and Content-Length HTTP headers are set implicitly as default by Testify and can't be added here.
Save newly created workflow, which then automatically gets invoked when the specified event occurs.
To see when a webhook has been executed and whether the execution has been successful, go to the workflow details, click on the context menu and select “History”.
The HTTP method is always POST and the payload depends on the event that triggered the webhook.
Property | Description |
|---|---|
| This is set to the identifier that can be set as an optional parameter at the webhook configuration (see above). |
| Depending on the event that triggered the workflow these are set. |
| Id of the workflow that triggered the event. Only set if the event was triggered by a workflow. |
| Id of the tenant. |
| Gives information about the event that triggered the webhook: 1 (issue), 2 (checklist), 3 (testobject), 4 (pdf), 5 (user), or 6 (timertrigger). |
| Tells whether 1 (created) or 2 (updated) triggered the webhook. In our case a checklist has been created, so 1 is set. |
| Only set if the triggering event is an update event. Shows the values that were changed in this update. |
| External Id of the object that triggered the webhook. In our case this is the external id of the created checklist. |
| URL where details of the object that triggered the webhook can be found. In our case the created checklist can be queried via GET-request to this URL. |
| Date and time when the event took place. |
IssueState
TestItemState
SubscriptionEntityType
EventActions
|
Here are some samples of sent information in the webhook payload:
Checklist created:
{
"WebHookIdentifier": null,
"IssueFilter": null,
"ChecklistFilter": {
"ExternalId": "0878ec9e-62f1-4e65-be5c-42856f611420",
"CreatedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"ModifiedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"AssignedToId": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"TestObjectId": "34229f43-df5b-4d96-9a48-d1778ebf952b",
"TestObjectTypeId": "f4256bc1-400d-4bfe-9a4d-d3f48fd7fd7f",
"State": 0,
"ChecklistTemplateId": "f4a42636-995c-4231-bbf5-919909e40a69",
"ScheduledFor": "2022-04-04T22:00:00Z",
"Score": null
},
"TestObjectFilter": null,
"PdfFilter": null,
"UserFilter": null,
"TimerFilter": null,
"TriggeredByWorkflowId": null,
"TenantId": "0d629d72-3831-4874-8151-4b97f55523ff",
"EntityType": 2,
"Action": 1,
"ChangedValues": null,
"EntityId": "0878ec9e-62f1-4e65-be5c-42856f611420",
"EntityUrl": "https://cloud.testify.io/tests/0878ec9e-62f1-4e65-be5c-42856f611420/data",
"CreatedAt": "2022-04-04T10:23:27.3557053Z"
} |
Issue created:
Everything looks very similar to the checklist created event, but here the IssueFilter is set and EntityType is set to 1 (issue).
{
"WebHookIdentifier": null,
"IssueFilter": {
"CreatedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"ModifiedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"AssignedToId": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"TestObjectId": "63be7657-2314-4704-b1d7-8de444f89039",
"TestObjectTypeId": "f4256bc1-400d-4bfe-9a4d-d3f48fd7fd7f",
"State": 1,
"IssueCategoryId": "c6246372-21df-49e5-b95e-073f000d775b",
"Severity": 2,
"Title": "test",
"Description": null,
"ScheduledFor": "2022-04-04T22:00:00Z"
},
"ChecklistFilter": null,
"TestObjectFilter": null,
"PdfFilter": null,
"UserFilter": null,
"TimerFilter": null,
"TriggeredByWorkflowId": null,
"TenantId": "0d629d72-3831-4874-8151-4b97f55523ff",
"EntityType": 1,
"Action": 1,
"ChangedValues": null,
"EntityId": "abb33d1f-6787-444b-b43f-aee7147c3d49",
"EntityUrl": "https://cloud.testify.io/issues/abb33d1f-6787-444b-b43f-aee7147c3d49",
"CreatedAt": "2022-04-04T10:30:26.5496694Z""
} |
Issue updated:
The issue has been resolved with a duration of 5 minutes.
Note the ChangedValues attribute that shows that duration and state were changed. Also Action has value 2 (updated) now.
{
"WebHookIdentifier": null,
"IssueFilter": {
"CreatedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"ModifiedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"AssignedToId": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"TestObjectId": "34229f43-df5b-4d96-9a48-d1778ebf952b",
"TestObjectTypeId": "f4256bc1-400d-4bfe-9a4d-d3f48fd7fd7f",
"State": 2,
"IssueCategoryId": "c6246372-21df-49e5-b95e-073f000d775b",
"Severity": 2,
"Title": "test",
"Description": null,
"ScheduledFor": "2022-04-04T22:00:00Z"
},
"ChecklistFilter": null,
"TestObjectFilter": null,
"PdfFilter": null,
"UserFilter": null,
"TimerFilter": null,
"TriggeredByWorkflowId": null,
"TenantId": "0d629d72-3831-4874-8151-4b97f55523ff",
"EntityType": 1,
"Action": 2,
"ChangedValues": {
"duration": {
"oldValue": null,
"newValue": 5
},
"state": {
"oldValue": 1,
"newValue": 2
}
},
"EntityId": "d9507dd0-d767-4ab9-8bf2-dc9f6c37bf22",
"EntityUrl": "https://cloud.testify.io/issues/d9507dd0-d767-4ab9-8bf2-dc9f6c37bf22",
"CreatedAt": "2022-04-04T10:34:47.8509246Z"
} |
As mentioned above additional parameters for sending authenticated webhook requests can be specified in the webhook “Parameters”. So the target of the webhook is able to verify the integrity of an incoming webhook request. This is possible by 2 differnt mechanisms:
Adding arbitrary HTTP-Headers: This consists of key-value pairs which are then sent in the HTTP headers, e.g. Username: {Username}, Password: {Password}. Please be aware that this should only be done when using a secure channel like HTTPS, TLS.
Signing the webhook request with a pre-shared secret: This adds the following two additional HTTP headers to the webhook request - Testify-Webhook-Signature and Testify-Webhook-Signature-Timestamp. The Testify-Webhook-Signature is a hashed value, which is created from a timestamp and the request payload by using SHA256 HMAC with the provided “secret” in the webhook parameters and then base64 encoding. Represented as: base64(HMACSHA256(TIMESTAMP + BODY))
To verify the signature, create the same SHA256 HMAC signature (containing of the Testify-Webhook-Signature-Timestamp and the request payload) with the provided secret, then base64 encoding and compare it to the Testify-Webhook-Signature sent in the request header. See following example:
public bool VerifyWebhook([FromBody] object body)
{
var secret = "my-secret";
var signature = this.Request.Headers.GetValues("Testify-Webhook-Signature").FirstOrDefault();
var timestamp = this.Request.Headers.GetValues("Testify-Webhook-Signature-Timestamp").FirstOrDefault();
var parsedBody = JsonConvert.SerializeObject(body);
using (var hmac = new HMACSHA256(Encoding.ASCII.GetBytes(secret)))
{
var encodedSignature = Convert.ToBase64String(
hmac.ComputeHash(
Encoding.ASCII.GetBytes($"{timestamp}{parsedBody}")));
return signature == encodedSignature;
}
} |
This example shows a complete use case using Testify API. First a testobject is created and for this testobject a checklist is instantiated. When the checklist is completed in Testify two webhooks are called, one that fetches the check results and one that informs us about a generated PDF for that checklist and downloads it.
Create testobject via Testify API:
Send POST-request
Endpoint: {StageBaseUrl}/public/testobjects?api-version=2.0
HTTP method: POST
HTTP headers: API key (secret, Subject, Tenant), Content-Type: application/json, Content-Length
Payload (approach 1): Both the internal id and the external id are automatically set by the system and are the same.
{
"testObjectTypeId": "F4BBD5AA-7F27-4D9E-976C-23AB258A21B9",
"title": "My new testobject",
"identifier": "my-new-testobject",
"description": "testobject created by api",
"parentId": null
} |
OR Payload (approach 2) including self-assigned external id: The external id is set to my-testobject and the internal id is automatically set by the system.
{
"testObjectTypeId": "F4BBD5AA-7F27-4D9E-976C-23AB258A21B9",
"title": "My new testobject",
"identifier": "my-new-testobject",
"description": "testobject created by api",
"parentId": null,
"id": "my-testobject"
} |
Testobject has successfully been created if response has statuscode 200 OK and payload contains external id of new testobject. If response statuscode is 400 Bad Request something in the request is wrong, but error details are provided in the payload.
Instantiate checklist for newly created testobject via Testify API:
Send POST-request:
Endpoint: {StageBaseUrl}/public/checklists?api-version=2.0
HTTP method: POST
HTTP headers: API key (secret, Subject, Tenant), Content-Type: application/json, Content-Length
Payload (approach 1): testObjectId contains the external id of the above created testobject.
{
"testObjectId": "306a9227-0ce6-4fd6-8418-bdbab6a474d7", // or "my-testobject"
"templateId": "f4a42636-995c-4231-bbf5-919909e40a69",
"assignedToId": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"scheduledFor": "2022-04-04T22:00:00.000Z"
} |
OR Payload (approach 2) including self-assigned external id:
{
"testObjectId": "306a9227-0ce6-4fd6-8418-bdbab6a474d7", // or "my-testobject"
"templateId": "f4a42636-995c-4231-bbf5-919909e40a69",
"assignedToId": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"scheduledFor": "2022-04-04T22:00:00.000Z",
"id": "my-checklist"
} |
Checklist has successfully been started when response has statuscode 200 OK and payload contains external id of new checklist instance. If response statuscode is 400 Bad Request something in the request is wrong, but error details are provided in the payload.
React to webhook informing us of completed checklist and fetch check results:
Prerequisites 1 - Before completing the checklist: Configure webhook that should be triggered (see above).
Event details: Scope: “Checklist”, Type: “updated”, Triggers: State = “Done”
Action details: Scope “Webhook”, Type: “trigger”, provide URL
Parse Webhook payload:
ChangedValues shows state change from 0 (open) to 3 (done) and new modifiedAt date.
EntityId is needed to fetch the checklist results.
{
"WebHookIdentifier": null,
"IssueFilter": null,
"ChecklistFilter": {
"ExternalId": "9033d3c6-5897-484c-a247-61cc4e636920",
"CreatedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"ModifiedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"AssignedToId": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"TestObjectId": "306a9227-0ce6-4fd6-8418-bdbab6a474d7",
"TestObjectTypeId": "f4bbd5aa-7f27-4d9e-976c-23ab258a21b9",
"State": 3,
"ChecklistTemplateId": "f4a42636-995c-4231-bbf5-919909e40a69",
"ScheduledFor": "2022-04-04T22:00:00Z",
"Score": null
},
"TestObjectFilter": null,
"PdfFilter": null,
"UserFilter": null,
"TimerFilter": null,
"TriggeredByWorkflowId": null,
"TenantId": "0d629d72-3831-4874-8151-4b97f55523ff",
"EntityType": 2,
"Action": 2,
"ChangedValues": {
"modifiedAt": {
"oldValue": "2022-04-04T13:53:05.463Z",
"newValue": "2022-04-04T14:18:45.7983551Z"
},
"state": {
"oldValue": 0,
"newValue": 3
}
},
"EntityId": "9033d3c6-5897-484c-a247-61cc4e636920",
"EntityUrl": "https://cloud.testify.io/tests/9033d3c6-5897-484c-a247-61cc4e636920/data",
"CreatedAt": "2022-04-04T14:19:36.2492712Z"
} |
Send GET-Request to fetch checklist results:
Endpoint: {StageBaseUrl}/public/checklists/{EntityId}/results/flat?api-version=2.0
HTTP method: GET
HTTP headers: API key (secret, Subject, Tenant)
Payload: no payload
The response should have status code 200 OK and gives details of the checklist instance with all testcases. Details to this response can be found below at “Structure of checklist results” section.
React to webhook informing us of generated PDF for checklist and download it:
Prerequisites 1 - Before completing the checklist: Configure workflow that automatically generates PDF.
Event details: Scope: “Checklist”, Type: “updated”, Triggers: State = “Done”
Action details: Scope: “PDF”, Type: “generate”, select PDF protocol profile and language
Prerequisites 2 - Before completing the checklist: Configure webhook that should be triggered.
Event details: Scope: “PDF”, Type: “Checklist PDF generated”
Action details: Scope “Webhook”, Type: “trigger”, provide URL
Parse Webhook payload:
EntityUrl is needed to get created PDF.
{
"WebHookIdentifier": null,
"IssueFilter": null,
"ChecklistFilter": {
"ExternalId": "9033d3c6-5897-484c-a247-61cc4e636920",
"CreatedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"ModifiedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"AssignedToId": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"TestObjectId": "306a9227-0ce6-4fd6-8418-bdbab6a474d7",
"TestObjectTypeId": "f4bbd5aa-7f27-4d9e-976c-23ab258a21b9",
"State": 3,
"ChecklistTemplateId": "7760b4d2-d8e0-45e2-ba41-19cfd0ecdda6",
"ScheduledFor": "2022-04-04T22:00:00Z",
"Score": null
},
"TestObjectFilter": null,
"PdfFilter": {
"PdfProfileId": "5a359ecf-4d29-40c3-853a-8a9a6868e12d",
"UserId": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157"
},
"UserFilter": null,
"TimerFilter": null,
"TriggeredByWorkflowId": "e4ac9840-a499-4d4f-bbcb-8103d5c289b0",
"TenantId": "0d629d72-3831-4874-8151-4b97f55523ff",
"EntityType": 4,
"Action": 1,
"ChangedValues": null,
"EntityId": "97c282e6-885d-4109-983f-14317ac29cda",
"EntityUrl": "https://cloud.testify.io/0d629d72-3831-4874-8151-4b97f55523ff/97/97c282e6-885d-4109-983f-14317ac29cda.pdf",
"CreatedAt": "2022-04-04T14:21:57.6884096Z"
} |
Send GET-Request to get created PDF and download it:
Endpoint: EntityUrl
HTTP method: GET
HTTP headers: no headers
Payload: no payload
The response should have status code 200 OK and gives the created PDF as payload.
All localizations implemented in Testify can also be used in the Testify API. Every tenant has a default language which normally is English (US). Following languages are available:
Iso-Code | Title |
|---|---|
bs | Bosanski |
de-AT | Deutsch |
en-GB | English (UK) |
en-IN | English (India) |
en-US | English (US) |
es-MX | Español |
fr | Français |
nl | Nederlands |
pt-BR | Português |
ru | русский |
zh-CN | 中文(中国) |
zh-TW | 中文(台灣) |
Send POST-Request:
Endpoint: {StageBaseUrl}/public/customfields?api-version=2.0
HTTP method: POST
HTTP headers: API key (secret, Subject, Tenant), Content-Type: application/json, Content-Length
Payload:
The label contains the respective iso code with the localized content and the default language must always be provided.
{
"customFieldKey": "my-custom-field",
"type": 1,
"label": {
"en-US": "my-custom-field",
"de-AT": "mein-benutzerdefiniertes-feld"
},
"isInternal": false,
"options": null,
"createdAt": "2022-04-06T13:28:19.688Z",
"createdById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"modifiedAt": "2022-04-06T13:28:19.688Z",
"modifiedById": "4ee99e3e-04fd-4ded-b4c6-1463c7b6a157",
"defaultLocale": "en-US",
"customFieldOptions": null
} |
The response should have status code 200 OK and gives the custom field key of the newly created custom field.
Checklist Template: Defines the structure of a checklist with its pages, sections and checks.
Checklist Template Revision: Is a revisioning mechanism for checklist templates. A checklist template revision can be in different states (see Enumeration types below).
Checklist Instance: Is an instance of a checklist template which is assigned to a certain user or group and where check results are added. A checklist instance can be created from a checklist template´s current (published) revision.
Check(Testcase): A checklist can contain 11 different types of checks with different parameters and result values (see details below).
Many endpoints use enumeration types in their request or response body. In the Testify API they are represented by their integer value. Some important examples are listed below:
Draft = 0, Published = 1, Deprecated = 2, Disabled = 4 |
Open = 0, InProgress = 1, Completed = 2, Done = 3, Verified = 4, Removed = 99 |
String = 1, Numeric = 2, Boolean = 3, DateTime = 4, Attachment = 5, Localization = 6, Array = 7, Attachments = 8, TestObjects = 9, GeoPosition = 10, Signature = 11 |
|
String = 1, Numeric = 2, Boolean = 3, DateTime = 4, LocalizedString = 5, StringArray = 6, NumericArray = 7, BooleanArray = 8, DateTimeArray = 9, LocalizedStringArray = 10, JsonStringArray = 11, TestObjectTypeArray = 12 |
|
The result type always refers to the TestCase Result Value Typeand the parameter type always refers to TestCase Plugin Parameter Type (see above, with examples about how the value can look like)
Testify offers 11 different check types (internally called TestCase Plugins). The different check types contain different types of data which are described in this section.
|
testify_booleantestcase
|
Possible parameters:
|
testify_calculation_testcaseThe result contains a list of numeric value results.
|
Possible parameters:
|
testify_datetestcase
|
Possible parameters:
|
testify_file_upload_testcaseThe result contains a list of attachments containing
|
Possible parameters:
|
testify_multi_selection_testcaseThe result contains a list of selected options (details about the options can be found in the test case plugin parameters).
|
Possible parameters:
|
testify_numerictestcase
|
Possible parameters:
|
testify_photo_upload_testcaseThe result contains an attachment with
|
Possible parameters:
|
testify_single_choice_testcaseThe result contains the selected label (details about the labels can be found in the test case plugin parameters).
|
Possible parameters:
|
testify_test_object_selection_testcaseThe result contains a list of ExternalIds of the selected test objects.
|
Possible parameters:
|
testify_texttestcase
|
Possible parameters:
|
testify_timetestcaseThe result contains the selected datetime (at time check the date is always set to
|
Possible parameters:
|
testify_geopositioncheckThe result contains the selected latitude and longitude.
|
Possible parameters:
|
testify_signaturecheckThe result contains the signature-file.
|
Possible parameters:
|
There are two endpoints where check results can be added. They differ in whether the checkId or the checkIdentifier ist set. Both - checkId and checkIdentifier- can be queried at the GET /public/checklists/{externalId}/results/flat endpoint. (which is described above)
POST /public/checklists/checkresult: Add check result by checkId.
POST /public/checklists/checkresult/identifier: Add check result by human-readable checkIdentifier.
|
Consider using a numeric check instead, as here the single values and also the calculated result needs to be sent as multiple values.
|
|
|
The result value contains a list of selected options (details about the options can be found in the test case plugin parameters).
|
|
|
The result value contains the id of the selected label (details about the labels can be found in the test case plugin parameters).
|
|
|
The result value contains the selected datetime (at time check the date is always set to
|
The result value contains the selected latitude and longitude
|
The result value contains the signature as file (only png allowed)
|