Help Contents

 

Background Tasks

updated by Catch Admin (Mar 09, 2016)

Resource: Background Tasks ( /api/backgroundtasks )

Collection of background tasks

Root Relation: BackgroundTasks

This resource supports the following methods: POST

Methods

POST

Starts a new background task.

Required Permissions

  • Enforced by task implementation

Status Codes

These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).

StatusDescription
202 - AcceptedReturned if the task was created successfully.
403 - ForbiddenIf you do not have permission to execute this job.
500 - InternalServerErrorIf the job handler for this background task encountered an unrecoverable error creating the job.

Example - Start project reindex

An example of starting the reindexing of a individual project by passing in the project's unique GUID identifier as a parameter to the 'Reindex' background task type.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "Optimize": true,
    "ProjectId": "c651ed19-5375-475a-a539-9f6401467130"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.1,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Queuing index events",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

202 - Accepted

Example - Start Project Reindex and Stream Progress

An example of starting the reindexing of a individual project by passing in the project's unique GUID identifier as a parameter to the 'Reindex' background task type. This also makes use of the 'StreamProgress' option which will stream progress updates back as a JSON array until the background task is complete.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "Optimize": true,
    "ProjectId": "c651ed19-5375-475a-a539-9f6401467130"
  },
  "StreamProgress": true
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

[
  {
    "Complete": false,
    "TotalElements": 10,
    "ProcessedElements": 1,
    "StartedAt": "2013-12-31T21:50:00Z",
    "ProgressInPercent": 0.1,
    "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
    "Message": "Queuing index events"
  },
  {
    "Complete": false,
    "TotalElements": 10,
    "ProcessedElements": 5,
    "StartedAt": "2013-12-31T21:50:01Z",
    "ProgressInPercent": 0.5,
    "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
    "Message": "Process queued events"
  },
  {
    "Complete": true,
    "TotalElements": 10,
    "ProcessedElements": 10,
    "StartedAt": "2013-12-31T21:50:00Z",
    "FinishedAt": "2013-12-31T21:50:02Z",
    "ProgressInPercent": 1.0,
    "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
    "Message": null
  }
]

Status Code

202 - Accepted

Example - Start reindex without clearing second-level cache

An example of starting the reindexing background task but disabling the clear second-level cache behavior. This can decrease time to reindex if no changes have been made to ET data except via the API/UI (e.g. you have not restored a database backup or run any queries to directly change the ET database).

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "Optimize": true,
    "ClearCache": false,
    "ProjectId": "c651ed19-5375-475a-a539-9f6401467130"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.1,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Queuing index events",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

202 - Accepted

Example - Start Reindex of All Incidents for a Project

An example of starting the reindexing for incidents only of a single project.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "Optimize": true,
    "IncidentsOnly": true,
    "ProjectId": "c651ed19-5375-475a-a539-9f6401467130"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.1,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Queuing index events",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

202 - Accepted

Example - Start Execution Package Reindex

An example of starting the reindexing of an individual execution package and all its children by passing in the package's unique GUID identifier as a parameter to the 'Reindex' background task type. Package reindexing does not clear the index, so this can be run without any loss of functionality to users to ET, unlike a project/ allprojects reindex.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "ExecutionPackageId": "c651ed19-5375-475a-a539-9f6401467130"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.1,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Queuing index events",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

202 - Accepted

Example - Start Script Package Reindex

An example of starting the reindexing of a individual script package and all its children by passing in the package's unique GUID identifier as a parameter to the 'Reindex' background task type. Package reindexing does not clear the index, so this can be run without any loss of functionality to users to ET, unlike a project/all projects reindex.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "ScriptPackageId": "c651ed19-5375-475a-a539-9f6401467130"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.1,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Queuing index events",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

202 - Accepted

Example - Start Requirement Package Reindex

An example of starting the reindexing of a individual requirement package and all its children by passing in the package's unique GUID identifier as a parameter to the 'Reindex' background task type. Package reindexing does not clear the index, so this can be run without any loss of functionality to users to ET, unlikely a project/all projects reindex.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "RequirementPackageId": "c651ed19-5375-475a-a539-9f6401467130"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.1,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Queuing index events",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

202 - Accepted

Example - Start All Projects Reindex

An example of starting the reindexing of all projects in Enterprise Tester without optimization, and skipping relationship reindexing.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "Optimize": false,
    "SkipRelationships": true
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.1,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Queuing index events",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

202 - Accepted

Example - Start Reindex of Specific Entities

An example of starting the reindexing of specific entities only. Unlike other reindexing tasks this one won't wait for the reindexing to complete, and is intended as a 'fire-and-forget' task you can quickly invoke to re-sync the index after making changes to entities directly in the database.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "Reindex",
  "Parameters": {
    "Optimize": false,
    "Entities": [
      {
        "Id": "f2a5fcee-3811-4672-abe1-2e26b7ebf8f9",
        "Type": "Requirement"
      },
      {
        "Id": "59780535-3cc6-431f-b8f6-5d4dc378bf5b",
        "Type": "TestScript"
      },
      {
        "Id": "f6b4fb38-b211-46f7-9a64-2fe3c10c3d59",
        "Type": "TestScriptAssignment"
      },
      {
        "Id": "c52aff95-42dc-4de9-8419-591ed959fd08",
        "Type": "Incident"
      }
    ],
    "SkipRelationships": true
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b

Response Body

{
  "Complete": false,
  "TotalElements": 4,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.1,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": null,
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

202 - Accepted

Example - Link a Ticket to a Script Assignment's Step Result

This example shows how to link a ticket to a Script Assignment's Step Result. Tickets is the term used for external incidents stored in defect trackers.
This background task allows you to link to a ticket using its unique key. As part of the linking process an associated incident synchronized with the ticket will be created in Enterprise Tester, if an incident does not already exist. An error (500) will be returned by this background task if the ticket can not be found, or is already linked to the Step Result.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "LinkTicketToStepResult",
  "Parameters": {
    "StepResultId": "ad3c8f9a-6959-4226-9b47-a0a601595de4",
    "Key": "TST-123"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/linktickettostepresult_d58d140f-fdd5-4d3e-b08b-4629b0b02da5

Response Body

{
  "Complete": false,
  "TotalElements": 3,
  "ProcessedElements": 2,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.67,
  "Id": "linktickettostepresult_d58d140f-fdd5-4d3e-b08b-4629b0b02da5",
  "Message": "Creating link",
  "Self": "http://localhost/api/backgroundtask/linktickettostepresult_d58d140f-fdd5-4d3e-b08b-4629b0b02da5"
}

Status Code

202 - Accepted

Example - Link a Ticket to a Script Assignment's Step Result (with External System Link Specified)

This example demonstrates passing an additional parameter to disambiguate the key for the ticket (ExternalSystemLinkId). This is necessary if the project has 1 or more associated Defect Tracker external systems, and the ticket keys are duplicated in both systems. Note: This additional parameter is also supported by the 'LinkTicketToAgileRunStep' and 'LinkTicketToAutomatedTestRunResultNode' task types.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "LinkTicketToStepResult",
  "Parameters": {
    "StepResultId": "ad3c8f9a-6959-4226-9b47-a0a601595de4",
    "ExternalSystemLinkId": "d8e4c6a3-5287-4b38-82f8-7791adcb6dc9",
    "Key": "TST-123"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/linktickettostepresult_d58d140f-fdd5-4d3e-b08b-4629b0b02da5

Response Body

{
  "Complete": false,
  "TotalElements": 3,
  "ProcessedElements": 2,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.67,
  "Id": "linktickettostepresult_d58d140f-fdd5-4d3e-b08b-4629b0b02da5",
  "Message": "Creating link",
  "Self": "http://localhost/api/backgroundtask/linktickettostepresult_d58d140f-fdd5-4d3e-b08b-4629b0b02da5"
}

Status Code

202 - Accepted

Example - Link a Ticket to a Agile Run's Step

This examples shows how to link a ticket to a Agile Run's Step. Tickets is the term used for external incidents stored in defect trackers.
This background task allows you to link to a ticket using its unique key, as part of this linking process an associated incident synchronized with the ticket will be created in Enterprise Tester, if an incident does not already exist. An error (500) will be returned by this background task if the ticket can not be found, or is already linked to the Agile Run's Step.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "LinkTicketToAgileRunStep",
  "Parameters": {
    "AgileRunId": "161e7eed-2cd7-45cc-97d9-a00f010e3aa4",
    "StepId": "79853241-febd-4f5d-93bf-4d380d024206",
    "Key": "TST-123"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/linktickettoagilerunstep_d58d140f-fdd5-4d3e-b08b-4629b0b02da5

Response Body

{
  "Complete": false,
  "TotalElements": 3,
  "ProcessedElements": 2,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.67,
  "Id": "linktickettoagilerunstep_d58d140f-fdd5-4d3e-b08b-4629b0b02da5",
  "Message": "Creating link",
  "Self": "http://localhost/api/backgroundtask/linktickettoagilerunstep_d58d140f-fdd5-4d3e-b08b-4629b0b02da5"
}

Status Code

202 - Accepted

Example - Link a Ticket to a Automated Test Run's Result Node

This example shows how to link a ticket to a result node in Automated Test Run. Tickets is the term used for external incidents stored in defect trackers.
This background task allows you to link to a ticket using its unique key. As part of this linking process an associated incident synchronized with the ticket will be created in Enterprise Tester, if an incident does not already exist. An error (500) will be returned by this background task if the ticket can not be found, or is already linked to the Automated Test's Result Node.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "LinkTicketToAutomatedTestRunResultNode",
  "Parameters": {
    "AutomatedTestRunId": "ad3c8f9a-6959-4226-9b47-a0a601595de4",
    "ResultNodeId": "3aaf3505-85ca-43c4-a822-fe468118aab7",
    "Key": "TST-123"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/linktickettoautomatedtestrunresultnode_d58d140f-fdd5-4d3e-b08b-4629b0b02da5

Response Body

{
  "Complete": false,
  "TotalElements": 3,
  "ProcessedElements": 2,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.67,
  "Id": "linktickettoautomatedtestrunresultnode_d58d140f-fdd5-4d3e-b08b-4629b0b02da5",
  "Message": "Creating link",
  "Self": "http://localhost/api/backgroundtask/linktickettoautomatedtestrunresultnode_d58d140f-fdd5-4d3e-b08b-4629b0b02da5"
}

Status Code

202 - Accepted

Example - Create an incident from a ticket

This background task is not normally executed directly, and is instead started by performing a POST request to 'StartCreateIncident' Link associated a ticket search result, but it can also be invoked directly as below. Note: TicketId is the internal identifier for the ticket (Issue) and is not the publicly visible 'Key' for the ticket.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Type": "CreateTicketLink",
  "Parameters": {
    "TicketId": "12345",
    "ExternalSystemLinkId": "3aaf3505-85ca-43c4-a822-fe468118aab7"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/ticketlinking_d58d140f-fdd5-4d3e-b08b-4629b0b02da5

Response Body

{
  "Complete": false,
  "TotalElements": 2,
  "ProcessedElements": 1,
  "StartedAt": "2011-12-31T21:50:00Z",
  "ProgressInPercent": 0.34,
  "Id": "ticketlinking_d58d140f-fdd5-4d3e-b08b-4629b0b02da5",
  "Message": "Creating incident",
  "Self": "http://localhost/api/backgroundtask/ticketlinking_d58d140f-fdd5-4d3e-b08b-4629b0b02da5"
}

Status Code

202 - Accepted