Enterprise Tester Help

Help

Welcome to Enterprise Testers online help system, you can currently find information for the following categories:

My Profile

My profile stores your personal details in Enterprise Tester as well as allowing you to change your password.

To update your profile:

MyProfileMenu.png

  1. Select ‘My Profile’ from the drop down under the username on the top right hand side.

MyProfileScreen.png

  1. You can update your email and name details.
  2. You can update your password by:

  3. You can also select to dock the tree navigator to the left by clicking the ‘Dock tree To Left’ checkbox.

  4. You can also select your default setting for test execution – multi- step or single step. The default setting for all new users is multi-step execution.

  5. Enterprise Tester supports both In Tray and Email Notifications.

Users can enable or disable either of these types of notifications, and can specify the project and types of events to be notified on.

Notes: These configurations apply to both In Tray and Email notifications.
Your system administrator will need to configure an email server before you can enable email notifications on this screen.

Notifications

Enterprise Tester supports in tray notifications. You can configure your notification settings on the ‘My Profile’ Screen as described in the previous section.

You can access your notifications by clicking on the notification icon next to your user name in the right corner or the screen. The number shown is the number of unread notifications. This number is updated every 15 sec.

The notifications list has a number of features easy to quickly view event notifications:

  1. Entity Icon for easy recognition of the entity type;
  2. User name of the person who made the change; and
  3. A hyperlink the entity so you can easily view the change.

Notifications.png

By default, the limit on the number of notifications on screen is 100. This number can be configured by your system administrator. Please refer to the section (see ConfiguringaMail_Server) for more detail.

Requirements

Capturing your requirements in Enterprise Tester allows you to take advantage of the requirement coverage reporting functionality once your test scripts have been created.

Requirements are stored under the requirements folder in the project in Enterprise Tester. Requirements can also be imported from external systems such as EA or JIRA, or even a CSV file.

Adding Requirements Packages

In order to allow you to group the requirements in a meaningful way you can add sub packages to the requirements packages.

To do this:

  1. Navigate to the requirements section of the project in the explorer view.
  2. Right click on the Requirements folder or a package within it and select Add Package. Or select the Add Requirements Package icon at the top of the tree view.

  3. Enter a name for the package and click on save.

The requirements package will be created under the selected project.

Moving Requirement Packages

You can move requirement packages if required.

To do this:

  1. Expand the explorer view until you can see the requirement package.
  2. Select the requirements package and drag it to the required location by clicking and holding your mouse down.

The requirement package and everything within it will move to the selected location.

Adding Requirements

Requirements can be added to the packages that you have created by either creating them directly in Enterprise Tester, importing existing requirements from a CSV, or by importing them from JIRA or Enterprise Architect.

To add a requirement directly in Enterprise Tester:

  1. Right click a package and select to add a requirement or select the add requirement icon at the top of the tree view, the Requirements Screen will appear.

  2. On the “Details” tab enter the requirements details:

  3. Click on ‘Save’.

Adding Attachments to Requirements

You can add attachments to requirements by clicking on the Attachments tab:

Nested Requirements

Enterprise Tester allows you to nest requirements, you can do this by right clicking the Requirement in the Explorer Tab and selecting Add Requirement. Alternatively you can drag and drop a requirement onto another requirement.

Viewing and Editing Requirements

Requirement Lists

You can view all requirements in a package by:

A list of all requirements in the package will be shown in the grid view.

The “Show Nested Items” tick box enables users to see all nested requirements in any sub-package of the selected Requirements package.

Filtering Requirements

Where a large number of requirements have been created within a single package, it is helpful to filter these records into more manageable groups.

To do this:

  1. Ensure your requirements are displayed in your grid view.
  2. Double click the Requirements package select view requirements.
  3. Click on the ‘Filter’ button to open the search screen.
  4. Select your search/ filter criteria and click on ‘Search’ to filter records and display results.

Additionally you can view requirements in the package you have selected and also any sub packages if required. Tick or un-tick the “Show Nested Items” box as required.

Viewing and Editing Requirements

There are several ways to open a requirement for editing:

Requirement Relationships

You can view and manage requirement Relationships from the Relationships tab.

Associated Requirements, Scripts, Script Runs, Automated Tests, Automated Test Runs and Incident relationships are displayed.

Adding Relationships

You can add relationships via this tab if you require.

To add a relationship, select the requirement you wish to associate and click the add button.

The Add Relationship pop up dialogue is displayed.

Select a Relationship Type:

Select a Destination:

You will be able to select a Requirement, Automated Test Script or Test Script to link to depending on the Relationship Type you have chosen to create.

Select a Direction:

Requirement to Requirement relationships have the following available directions:

There is only one direction available for:

This is:

Click OK and the relationship will be created and saved.

Removing Relationships

You can remove a relationship by selecting a Requirement, Automated Test Script or Test Script that is related to the Requirement you are viewing, and then by clicking the Remove button.

Note: You will not be prompted for a confirmation to remove this relationship.

Editing Relationships

You can edit a relationship direction by selecting a Requirement that is related to the Requirement you are viewing, and then clicking the Edit button.

Change the relationship direction in the pop up dialogue box and click ok to save it.

Viewing Requirements History

You can view the history of changes made to a requirement.

To do this:

  1. Select the History tab of the requirement when you have the requirement open for editing - the history of changes will be displayed.

You can filter the list of changes displayed by selecting from the filters available and clicking on ‘Search’, the filtered list will be displayed.

To clear the filter click on ‘Reset’.

Requirement Versions

Enterprise Tester also creates versions of requirements each time a set of changes are made.

The Versions tab lists the versions that have been created over time and provides the following information:

This tab also displays detailed information for the selected version showing the difference between that version and the latest version. Details provided are:

Traceability Export

A requirement traceability export format is available from the requirement summary view. This export allows you to view you requirements and any related entities, giving you full traceability.

Similar to the normal export form the requirement summary screen, you can export your requirements and all related columns into a CSV format.

In addition to the basic requirement fields you can also export (optionally) all the related Test Script ( Manual and Automated), Script Run (Agile, Manual, Automated) and Incident information In addition, you have the option to include fields specific to these other entities as well e.g. JIRA Issue ID.

You can access the traceability export configuration screen by clicking the Traceability button on the navigator.

ReqTraceabilityExport.png

The configuration screen allows you to choose the scope of the export including the entities and detail to include.

ReqTraceabilityConfig.png

Administration

Help on a range of Administrative tasks is available:

Additional documentation is also available in the documentation section of the Enterprise Tester website.

Configuring a Mail Server

Enterprise Tester supports the ability to configure a mail server to support event notification.

To configure a mail server, from the Admin tab, expand Configuration and double click on Mail Server.

Enter the details for your mail (STMP) server.

MailServerConfig.png

Setting Description
EnableCheck to enable your mail server.
HostEnter the host name of your mail server.
PortEnter the port to use to retrieve mail from your mail server. In general the ports for SMTP servers are: SMTP - port 25 Secure SMTP (SSMTP) - port 465 Secure SMTP (using StartTLS) - port 587
TimeoutEnter the Timeout in Millisec
UserNameThe user name used to authenticate the account
PasswordThe password used to authenticate the account
From AddressThe email address that will be used as the sender in the email (Note that this does not work for Gmail as this provider does not allow impersonation)
Email PrefixThis the prefix that will be added to email subject

Here are some examples of how to configure the settings for Gmail, Yahoo and Hotmail/livemail/Outlook.com:

GmailYahooHotmail/Live mail/Outlook.com
Host: smtp.gmail.com
Username: full gmail address e.g. user@gmail.com
Password: gmail password
Port: 587
SSL: yes
Host: smtp.mail.yahoo.com
Username: full yahoo address e.g. user@yahoo.com
Password: yahoo mail password
Port: 465
SSL: yes
Host: smtp.live.com
Username: full hotmail address
Password: hotmail password
Port: 587
SSL: yes

Custom Fields

Custom Fields provide flexibility to capture additional data within the application. Specifically, custom fields can be added to requirements, test cases, test cases in your execution sets and incidents. This feature allows you to add additional fields according to your needs in order to record additional information against these entities. A wide selection of field types can be created including:

*When using the Multi-Cascade Select field for multi-level cascading select (>2 levels), picklists are not configurable within Enterprise Tester. Values will be pulled from a configured defect tracker e.g. JIRA. You must have a defect tracker configured in order to use this custom field.

Creating Custom Fields

To creating custom fields complete the following steps:

  1. Click on the ‘Admin’ tab.
  2. Click to expand ‘Extensions’ from your tree view.
  3. Click on ‘Custom Fields’.
  4. The Configure Custom Fields list view will display.
  5. Click on ‘Add’ from the window toolbar.
  6. The ‘Field Configuration’ screen will open.
  7. On the ‘Details’ tab, enter a name for your field.
  8. In the Label field, enter the name of the field as you would like it to appear on screen to users.
  9. Click the dropdown button on the ‘Type’ field to select the type of field you would like to create.
  10. If the field is mandatory to complete, click the ‘Required?’ field, otherwise leave it blank.
  11. Include a brief description in the Description field.
  12. Click on the ‘Entities’ tab to select the types of entities (Incident, Requirement, Test Scripts) which will include the custom field. Note that you can use the same custom field across multiple entities.
  13. Click on the ‘Scope’ tab. Here you can select the organization(s) and/or project(s) that will include the custom field. Here you can also apply the custom field to all dependent projects or only to independent project. Apply the custom field to all dependent projects the custom field will be apply to all projects that are not marked as Independent n the project configuration screen. Please refer to the Managing Project help topic.

CustomFieldScope.png

  1. By adding scope for an organization, all projects for that organization will use the custom field for the entity selected. You can add specific custom fields for specific projects by including them here. When you specify the scope, entities will be updated to include the new field i.e. requirements, scripts and incidents that have previously been created will be updated to include the new custom field. If the field is mandatory, the user will be prompted to add this additional detail before saving.
  2. Click ‘Save Changes’ at the bottom right hand corner.

Creating a Multi Cascade Select Custom Field

Creating a multi-cascade select custom field is similar to creating any other custom field within Enterprise Tester. The values used to populate the picklist values for the multi-cascade select field are pulled from the defect tracker e.g. JIRA. A defect tracker must be configured to create this custom field successfully.

Note: Enterprise Tester may need to perform a “Refresh Lookup” before new custom fields in your defect tracker are available within Enterprise Tester.

To create a multi-cascade select custom field:

  1. Follow the steps 1-8 described in the section above.
  2. Click the dropdown button on the ‘Type’ field and select “Multi Level Cascade Select”
  3. The “Options” section will display. Select the defect tracker that contains the Multi Level Cascade Select Field.
  4. Select the Multi Level Cascade Select field in the defect tracker to map to in the Field dropdown. The values stored for this field in your defect tracker will be used as the values in Enterprise Tester.
  5. If the field is mandatory to complete, click the ‘Required?’ field, otherwise leave it blank.
  6. Include a brief description in the Description field.
  7. Click on the ‘Entities’ tab to select the types of entities (Incident, Requirement, Test Scripts) which will include the custom field. Note that you can use the same custom field across multiple entities.
  8. Click on the ‘Scope’ tab. Here you can select the organization(s) and/or project(s) that will include the custom field.
  9. By adding scope for an organization, all projects for that organization will use the custom field for the entity selected. You can add specific custom fields for specific projects by including them here. When you specify the scope, entities will be updated to include the new field i.e. requirements, scripts and incidents that have previously been created will be updated to include the new custom field. If the field is mandatory, the user will be prompted to add this additional detail before saving.
  10. Click ‘Save Changes’ at the bottom right hand corner.

When you view the screen you have applied your custom field to, it will display the field with the values from JIRA.

Configuring Pick Lists

When Combo Boxes, Multi Select boxes, Radio groups or Checkbox groups are created you will need to configure the selection lists. These can be configured in the same way as other non – user defined dropdown fields. Please refer to the Configuring Pick Lists help topic.

Sorting Custom Fields

Custom Fields can be sorted by entity. This allows you to specify the order that the fields will appear on your requirement, test script or incident. From the Configure Custom Fields screen:

  1. Click on the ‘Sort Fields’ button on your toolbar.
  2. The Order Custom Fields screen will open. Click on the dropdown to select the entity type.
  3. You can rearrange the order of your fields by either selecting your field and using the drag and drop method or by highlighting your field and clicking on the ‘Move Up’ or ‘Move Down’ buttons.
  4. Click ‘Save Changes’ from the toolbar.

CustomfieldSortOrder.PNG

Granting Permissions

User permissions can be granted at the application level (user and group) or at the project level. Permissions are granted in hierarchical manner and permissions granted at the application level will takes precedence over all other permissions assigned at the project level. If restricted access to some projects is required, then permissions should be granted at the project level.

Assigning Application Wide Permissions

Application level permissions are granted at the user and group level. To assign users or groups application wide permissions, you will need to be an Enterprise Tester application administrator. Follow these steps to assign permissions:

  1. Navigate to the Admin page.
  2. Click on the arrow to expand either the 'Users' folder or the 'Group'folder.
  3. Double click on the user or group you want to add permissions to.
  4. Click on the 'Permissions' tab.
  5. Here you can select to assign the permissions to grant the user or group. You can either select the whole group of permissions or select individual permissions within each group of permissions.
  6. Once complete, click on 'Save' to apply the permissions.

GroupPermissionsApplicationWide.png

Assigning Project Only Permissions

To grant permissions to a group or user for a specific project only, you must first assign the user or group to the project and then assign the permissions you wish to grant. Note that if the user has been granted greater permissions at the application level then these will take precedence.

Here are the steps to granting project permissions:

  1. Assign the user or group to the project. To do this, from the navigator click on the arrow beside the project. This will reveal the 'Users' and 'Groups' folder under the project. Then from the navigator, click to select the user or group to assign to the project and drag and drop the user or group to the respective User or Group folder under the project. Note for users only, when editing user accounts, you can assign the user to specific projects on the ' Assign Projects' tab.
  2. Double click to select the user or group. The permissions tab wil lappear under the project and assign the required permissions.

ProjectPermissionsTabForGroup.png

Available Permissions

There are 4 categories of permissions and 22 defined permissions provided in Enterprise Tester that can be used to control access to the various application features.

The five categories include:

• Administration
• Resources
• Project
• Reports
• Test Management

These categories can be expanded or collapsed as required by clicking on the + or- icon next to the name. Selecting any of these categories automatically selects all the permission they contain.

The available permissions are defined in the table below:

CategoryPermissionDescription
AdministrationManage OrganizationAllows users to manage organizational level details
Manage DashboardAllows users to manage organizational level dashboards
Manage User and Group SecurityAllows users to set security
Manage Organization ReportsAllows users to manage organizational level reports
Edit Organization Pick ListsAllows users to manage organizational level pick lists
Manage EA ConnectionsAllows users to manage EA connections
Manage Defect TrackerAllows users to manage Defect Trackers
Manage Modules and Plug-insAllows users to manage Modules & Plug-Ins
ResourcesExportAllows users to Export Data From Enterprise Tester
ImportAllows users to Import Data Into Enterprise Tester
External LinksAllows users to manage External Project Links
ProjectManage Project DashboardAllows users to manage project level dashboards
Manage Project ReportsAllows users to manage organizational level reports
Edit Project Pick ListsAllows users to edit pick lists
ReportsAllows users to create and run reports
Test ManagementManage RequirementsAllows users to manage requirements
Manage ExecutionAllows users to organize test execution sets
ViewAllows users to view scripts
Assign TestersAllows user to assign scripts to a tester
Execute TestsAllows users to execute tests

Viewing User Permissions

An easy way to review the permissions granted to a user is to click on the Assigned Permissions tab when viewing a user. Here you can see all the permissions granted at the application level and at the project level.

To make it easier to review and manage user permissions, a summary is available through the administration tab, giving an overview of application and project level permissions at a glance.

To access the permissions summary screen, click on the “Admin” tab and then double click on the user whose permissions you wish to review. Click on the “Assigned Permissions” tab to access the permissions at a glance.

UserAssignedPermissions.png

Managing Groups

Adding Group

You can add groups to Enterprise Tester through the Admin section which can be accessed from the Admin tab on the navigator.

To add a group:

  1. Select the ‘Admin’ tab in the navigator
  2. Click to expand to the Users folder
  3. Right click on the ‘Groups’ folder and select ‘Add Group’ - the Add Group screen will display
  4. Complete the following details:
  5. Click on the 'Permissions' tab to begin assigning permissions. For more information on granting permissions, see the help topic Granting_Permissions
  6. On the 'Assign Users' tab you can select the users to associate with the group. Type in the user's name or username and select the user from the results returned. Note that permissions granted here will apply application wide and not just to the assigned projects.
  7. Click on ‘Save’ to create the group.

Editing Groups

To edit a group:

  1. Select the ‘Admin’ tab in the tree view.
  2. Click to expand to the ‘Groups’ folder.
  3. Right click on the user folder and select View Groups - the view users screen will display.
  4. Double click on a group to edit.

The Group screen will appear and you can now update the details.

Deleting Groups

To delete a group:

  1. Select the ‘Admin’ tab in the tree view.
  2. Expand to the Groups folder.
  3. Right click on the ‘Groups’ folder and select View Users - the view users screen will display.
  4. Double click on a group to edit them.
  5. Click ‘Delete’.
  6. Click on ‘Yes’ to the prompt - the group will now be removed.

Managing Picklist Values

Picklists for the ET standard fields can be managed at either the project level or at the organisation level.

Managing Picklist Values at the Organization Level

Managing your picklist values at the organisation level is useful when you have standard field values that apply to the majority of your projects. When new projects are created, they will retain the organization picklist values when created. Note however, that changes to picklist values at the organisation level will only apply to new projects. Existing projects will need to be updated individually at the project level.

The picklist for custom fields are applied globally. This means there is only one set of values for a particular custom. It is easiest to manage your custom field values at the organization level.

To edit your organization picklist values, navigate to the Admin tab. Expand your organization, then either double click on your project or right click on your organization and select Edit Organisation from the menu.

On the bottom right corner of the Edit Project screen, select the edit picklist button. The edit picklist screen will appear allowing you to select the field that you wish to update or edit.

EditingPicklistValuesOrganisation.png

Managing Picklist Values at the Project Level

Managing your picklist at the project level is convenient when you have a different set of field values for your project than for your organization. From the project level you can add edit your standard field values to values specific for your project.

Note that there is only a single global list of custom field values and the picklist is best managed at the organization level. Updates can be made to Custom field picklist values at the project level but they will also apply to all other projects using that custom field.

To edit your project specific picklist values, navigate to the Admin tab. Expand your organization and then expand the Projects folder. Then either double click on your project or right click on your project and select Edit Project from the menu.

On the bottom right corner of the Edit Project screen, select the edit picklist button. The edit picklist screen will appear allowing you to select the field that you wish to update or edit.

EditingPicklistValuesProject.png

Managing Projects

Creating Projects

An unlimited number of projects can be created in Enterprise Tester. You can manage projects through the admin section of Enterprise Tester. To add a project:

AddProject.png

AddProjectTemplate.png

DefaultProject.png

b. Agile – This template provides an agile project set up option. The project structure is as follows:

AgileProject.png

In addition, the agile project template also adds the number custom field, Story Points to User Stories (Requirements) and has the following set of picklist values:

FieldPicklist Values
Incident ResolutionDuplicateCannot ReproduceWon't FixFixedIncomplete
Incident StatusOpenIn ProgressResolvedClosedReopened
Incident Type BugNew Feature Task
PriorityBlockerCriticalMajorMinor Trivial
Requirement DifficultyHighMediumLow
Requirement Status In Progress Review PendingApproved
Requirement TypeUser StoryTaskEpic
StatusIn ProgressReview PendingApproved
Test TypeSmokeFunctionalRegressionNon-functionalUser Acceptance

c. Cascade – This template provides a hybrid option of classical and agile project set up. The project structure is as follows:

CascadeProject.png

In addition, the Cascade project template has the following set of picklist values:

FieldPicklist Values
Incident ResolutionDuplicateCannot ReproduceWon't FixFixedIncomplete
Incident StatusOpenIn ProgressResolvedClosedReopened
Incident TypeBugNew FeatureTaskImprovement
PriorityBlockerCriticalMajorMinorTrivial
Requirement DifficultyHighMediumLow
Requirement StatusIn ProgressReview PendingApprovedRequires ReworkRejectedOn Hold
Requirement TypeUser StoryTaskEpicFunctionalNon FunctionalUser Interface
StatusIn ProgressReview PendingApproved Requires Rework RejectedOn Hold
Test Type SmokeFunctional Regression Non-functionalUser Acceptance

Once you have added you project name and selected the appropriate template, click save to open the add project screen.

FieldDescription
OrganizationSelect from the pick list of Organizations you have defined.
NameA name that identifies the project.
TypeEnter a name that identifies the type of project.
ManagerSelect the Project Manager from the pick list of users .
Picklist ValuesHere you can select to either inherit your picklist values ( Inbuilt and custom fields) from the organization picklist or have an independent set of picklist values for your inbuild fields.
Auto-numberYou can select auto-numbering of requirements and/or scripts
Read only numbersYou can configure the requirement and/or script number fields to be read only.
Start DateThe start date of the project.
End Date EstimateThe end date of the project.
DescriptionThe project description.

EditProject.png

Assigning Users to Projects

Users must be assigned to projects and can only access projects where they have been assigned; user access is also limited by associated permissions. A point to note here is that if a user has permissions granted at the application level, they will only require project specific permissions to elevate their permission level

You can assign users to the project in the Assign Users tab of the project:

  1. Open the project by right clicking and selecting Edit Project or by double clicking the project.
  2. Select the Assign Users tab.
  3. You can then add users by simply typing in the user name and selected from the filtered results or by using the drop down and selecting the user.

AddingUsersToProjects.png

Assign User Groups to a Project

Groups of users can be assigned to projects and project permission can then be assigned to the group. Group permissions at the application level will take precedence. You can assign groups to projects similarly to adding users directly to projects.

Time Tracking

You can also set the time to be used for tracking progress for a project by selecting the Time Tracking Tab.

Here you can select:

Working Hours Per Day The number of hours in a working day (1 - 24).
Working Days Per Week The number of days in a working week (1 - 7).

Version Control

You can add the following version control details for a project:

  1. Type the type of version control application you are using (selected from a supported list).
  2. Repository Url the url path for the version control repository you are configuring.
  3. Working Copy Path the working copy path for the version control repository you are configuring.
  4. Username a gateway user to access the repository.
  5. Password the password for the gateway user used to access the repository.
  6. Executable Path the path to the executable for the version control application.
  7. Additional Arguments any additional arguments required for the repository executable.

Note that you can choose to inherit Version Control from the organization. If you share version control repositories across Projects this enables you to define the connection once.

Managing Your ET License

To manage your Enterprise Tester License, from the Admin tab, expand the Configure folder. Double click on License.

License.png

Here you will be able to view your license parameters including the maximum number of concurrent user, maximum number of named users and the start and expiry date of your license.

Server Key

Here you will also find your server key and field for applying your license text. The license text is specific to your server key. In Stable Server Key Generation mode, the server key is affected by the following parameters:

  1. Machine Name
  2. Processor Count
  3. Operating System Name
  4. Operating System Version

If you are planning to upgrade any of these parameters please be aware that you server key may change and you will need to request a new license text from the Catch Support team.

Managing Your Organization

During the installation of Enterprise Tester, the organizantion is set up with a basic profile. These details are not permanent and can be updated by a system administrator.

You can update or edit your Organization details by expanding the Organisation folder and right clicking on your Organization's name. Select Edit Organisation from the menu.

EditOrganisation.png

From the organization set up screen, in addition to providing the organization details, you can set up the external version control, add Enterprise Architect connections and configure your pick lists.

EditOrganisationScreen.png

Subversion, Perforce and GIT are supported version control applications. Once version control is configured, projects that are created can choose to inherit version control from the organisation.

You will also notice that on the Organisation edit screen that you can configure picklist values and connections to Enterprise Architect (EA) databases or EAP files. Picklist values that are configured at the organisational level will propogate through to to the projects. This is useful when you have a default set of values for your inbuilt and custom fields that apply to all or most of your projects. Configuring your picklists and EA configurations at the Organisation level will help reduce the effor trequired when setting up your projects.

Search Indexing

Enterprise Tester features a comprehensive search engine which will periodically require search indexing to be performed.

Certain actions (such as adding custom fields) trigger a re-index to be performed. This enables the new information to become searchable.

Re-indexing can take anywhere from 5 to 60 minutes depending on many factors including database performance, IO performance of the disk where the Enterprise Tester indexes are being stored (a slow SAN/NAS based disk can impact on indexing and search performance) and the number of records and relationships stored in Enterprise Tester. As an example, during the testing of this feature a database with 100,000 entities took 30 minutes to re-index.

Performing a Re-index

If a re-index is required and an Administrator logs into Enterprise Tester – they will be redirected to the Indexing Administration page.

Image1.png

As an Administrator you can also access the Index screen by double clicking the Indexing node in the explorer tree:

Image2.png

To Re-index:

  1. Ensure it is an appropriate time to perform the re-index, it is recommended that you perform re-indexing out of hours or during off peak times. Users can still log in while the re-index is underway, but results in searches, grids and graphs will be inconsistent until the re-indexing process has completed.
  2. Click the “Re-index Now” button.
  3. Select “—All Projects –“ from the Project dropdown.
  4. Check “Optimize” if required (selecting Optimize will result in smaller and more efficient search indexes, however the re-indexing process will take longer and may affect users working in the system). Click “OK”

Image3.png

A reindex progress bar will be displayed:

Image4.png

A confirmation of re-index completion will be displayed:

Image5.png

When the re-index completes, the indexing window should refresh and the value “Requires Index” value should be “No”.

Image6.png

Other Indexing Administration Tabs

Changing the indexes folder location

By default the location of the Indexes folder will default to the "Data" folder of your installation. The indexes folder can grow up to 1 gigabyte in size, so if you don't have a lot of space free on your installation drive, or prefer to store data in a different location, you can change the web.config file to specify this location. See the app-setting-configuration mini-guide for details of how to do this.

Version Control

Enterprise Tester integrates with a number of popular Distributed Version Control System (DVCS).

This integration will transparently commit copies of baselines created for a project or package to source control, allowing test artefacts to be stored in a source code repository, allowing correlation of test artifacts with versions of a software code base.

Initial Setup

To enable version control integration with Enterprise Tester, the general steps are:

Configuration

Version control can be configured at an organisation or project level.

OrganisationVersionControl.PNG

In each case you will be required to supply the following details:

KeyValue
TypeType of version control repository to integrate with
Repository UrlUrl of the repository - this could be a standard HTTP URL, but depends on the type selected (for instance when using git it's OK to use an SSH style url)
Working copy pathWhere the repository is checked out to (this is where the baselines will be stored on the local disk) e.g. c:\data\baselines\

Note: currently the working directory must be created and checked out initially by the user, Enterprise Tester will not perform an initial checkout itself
UsernameThe username of a user with permissions to commit to the repository, in some cases this can be left blank i.e. when using SSH, or when the repository allows anonymous writes
PasswordThe password of a user with permissions to commit to the repository, in some cases this can be left blank i.e. when using SSH, or when the repository allows anonymous writes
Executable PathThis is the path (including filename) to the executable used to perform the source control actions so for example if using GIT integration, you would need to have git for windows installed, and you would then configure the executable path to be: c:\Program Files (x86)\Git\bin\git.exe
Additional ArgumentsAny additional arguments specified will be automatically added to every command executed using the executable (specified in Executable Path) - this is useful in the case of troubleshooting for instance, where you may want to pass in additional flags to force more verbose error messages and logging

Once you have configured version control an organisation level, to then use that version control repository you must configure the project repository to use the value "Inherit From Organisation" for the version control type.

InheritFromOrganisation.PNG

In this case project baselines will stored in child folders, based on the name of the project. If version control settings however are configured directly at the project level, baselines will be stored directly into the working directory folder.

Additional Info

Please consult the topics for each version control system, which provide more details are about specific setup steps for each version control type:

GIT

GIT is a popular DVCS (Distributed Version Control System) - supported by Enterprise Tester version 4.4 and above.

Setup

Step #1 - Installing GIT for Windows

To setup GIT integration, you must first install Git for Windows - which can be downloaded from the git-scm.com website.

Once downloaded, run the installation on the Enterprise Tester server.

Last of all, you will want to add the git "bin" folder to your path, to do so:

You should now be able to launch a command prompt and type "GIT" and see a version message like so:

C:\> git

usage: git [--version] [--exec-path[=]] [--html-path] [--man-path] [--inf-path]
           [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
           [--git-dir=] [--work-tree=] [--namespace=]
           [-c name=value] [--help]
            []

....

Step #2 - Cloning your repository

Next you need to clone your repository to a local directory on your Enterprise Tester machine. It the case of bitbucket or github, you can find the URL and directions on how to clone your repository on the home page for the repository.

If you intend on using SSH with a service such as github or bitbucket then you will need to:

  1. Login to the server using the same username as the identity configured for the application being used by Enterprise Tester.
  2. Generate an SSH Key (be sure to NOT password protect the SSH Key)
  3. Add it to your github or bitbucket account.

Github provide a handy guide on how to generate an SSH Key.

At this point you should now be able to clone the repository to a local directory of the machine - so commence with the clone, here an example of cloning from bitbucket:

git clone https://jbloggs@bitbucket.org/jbloggs/jbloggs_et_project.git

Once cloned, you may need to switch the branch of the repository to the branch you want Enterprise Tester to commit to (this can be done using the git checkout command).

git checkout QA

Step #3 - Check Commit Works

Once you have cloned the repository, we suggest performing a test commit (this will allow you to ensure that if using SSH, git does not prompt for a password when committing, and allows you to permanently accept SSH/SSL certificates etc.)

You can do this by:

You should see the new file is added to the remote git repository on the correct branch.

Step #4 - Setup

You are now ready to configure Enterprise Tester at either the project or organisation level - a standard GIT configuration when using a git repository hosted on bitbucket may look like this:

ExampleConfig.PNG

Step #5 - Testing

Once you have setup the configuration for your project, you can test the connection by creating a baseline for a small requirements or scripts package. You should be able to confirm it worked by checking the list of recent commits for your git repository on the remote server.

How it Works

The command flow executed by the synchronizer when creating a baseline for a project with git integration turned on is:

Perforce

Enterprise Tester supports integrating with Perforce version control when creating baselines.

Prerequisites

You must have the perforce command client installed onto the Enterprise Tester server for perforce integration to work (p4.exe). To install it go to the perforce website and download the version of the client applicable for your perforce version.

Once installed, you will normally find the executable is available at this path: C:\Program Files\Perforce\p4.exe

Setup

Perforce integration relies on setting up a workspace on the local disk of the Enterprise Tester server, pointing to the depot on the perforce server.

Once setup you can then configure Enterprise Tester at the project or organisation level, specifying the location of the p4 executable, the workspace folder, and the login and password to use when accessing the perforce depot (login/password are optional).

ExampleConfig.PNG

Subversion (SVN)

Enterprise Tester supports integration with subversion when creating baselines.

Setup

Step #1 - Download and Install Subversion Client

On the Enterprise Tester server, download and install subversion - we generally suggest using the SilkSVN or CollabNet packages.

The installation should automatically add subversion to your path, you can normally confirm this by launching a command prompt and typing "svn", you should see something like this if subversion is installed:

C:\> svn
Type 'svn help' for usage.

Step #2 - Checkout the Subversion Repository

Next you need to checkout the subversion repository to a folder on the local machine, this can be done using a command like so:

svn checkout https://svn.corpserver.com/svnroot/myproject/trunk/baselines baselines

This will checkout the repository with the URL "https://svn.corpserver.com/svnroot/myproject/trunk/baselines" to the folder "baselines" within the current directory.

Step #3 - Configure Version Control settings

Here is an example the configuration necessary for Subversion to work on a standard windows server:

ExampleConfig.png

Step #4 - Test Setup

This assumes you've already followed the rest of the instructions for setting this up - in particular - you must have done a svn checkout before this will work

At this stage you are now ready to test the functionality:

To start with - we recommend verifying that you have the subversion settings correct. You can do this by running a the following from a command prompt.

"[executable path]" --username [username] --password [password] --config-dir %tmp% update [repository url] [working copy path]

You need to copy the values of each of these from the ET configuration screen. Here's how the finished version would look for example configuration above:

"C:\Program Files (x86)\Subversion\bin\svn.exe" --username jbloggs --password password --config-dir %tmp% update https://svn.corpserver.com/svnroot/myproject/trunk/baselines c:\data\et\subversion\baselines\

If this runs successfully you should see output like the following (revision will likely not be 0 but should be a positive integer):

At revision 0.

If this doesn't run from the command line - then it won't work in ET. Look at the error message for guidance.

Next you need to ensure you can commit changes:

cd c:\data\et\subversion\baselines\
notepad test.txt 
[enter some text in the file and save it]
svn add text.txt
svn commit -m "test commit"

Once the command line is working correctly we suggesting creating a baseline for a small package - if you receive no errors when creating a baseline, review the commit history for your subversion repository and confirm the baseline.zip file was added correctly.

REST API

Overview

Enterprise Tester provides a REST API (Application Programming Interface) that can be used for retrieving and manipulating Enterprise Tester data without having to interact with the user interface.

There are many use cases for the API, but some common examples include:

The REST API is based on open standards, and you can use any web development language to access the API, or a tool such as CURL to make simple requests.

Enterprise Tester's REST API provides a way for applications to access resources (Entities) via a URI (Uniform Resource Identifier) e.g. a path.

To use the REST API your application will make an HTTP request and then parse the response which may include a payload as well as a status indicating if the request was succeedful.

Enterprise Tester's API uses JSON (JavaScript Object Notation) as the default format for its entities, and standard HTTP methods such as GET, POST, PUT and DELETE (Analogous to Read, Create, Update and Delete i.e. CRUD) to perform actions on those entities. Note: Not all resources support all HTTP methods, see the Resources list for a description of each resource, the methods it supports, and whether TQL or OData querying methods are supported.

URI Structure

Enterprise Testers URIs have the following structure:

http://host:port/applicationpath/api/resource-name

In the resource help topics the URI templates are displayed like so:

/api/project/{id}

Values surrounded by braces (such as {id} above) are parameter substitutions, where this part of the URI would be replaced with an appropriate value. All URI's already include the required /api fragment as well, and the examples included with each method supported by a resource show these parameters with example values.

So for a local instance of Enterprise Tester, to GET the details of a single project you would take the template above, replace the ID parameter, and prepend the site's base path (also called the application path, or site.root.url in the Enterprise Tester documentation) - after which you may end up with a URI that looks like this:

http://localhost/EnterpriseTester/api/project/a1d44feb-01b5-4f85-a18d-a03f00be87f6

Permissions

There is no specific permission required to use the API - Any Enterprise Tester user can access the API, but the features they can use will be limited by the permissions they have been granted. Each Resource topic lists the necessary permissions (if any) required to access the resource, and a summary of all resources with associated permissions required for each HTTP method are available in the Permissions topic.

Getting Started

To get started with the API, please refer to the Resources list, this provides the list of Resources (Entities) currently exposed, along with the methods they support and examples of requests and responses, including parameters, headers and status codes.

We also have a section where common features of the API are discussed, which can provide useful background information for those trying to develop against the Enterprise Tester API.

We also post tips and guides on how to use the API on the Catch Software Blogs which we update regularly.

Feedback

We would love to hear your feedback and feature requests on the API - Catch Software are working hard to make it as easy as possible to extend Enterprise Tester. Get in touch with our Support Team, we would love to hear how you are using the API, what's worked well and what could be improved.

API Features

In the following section general features of Enterprise Testers REST API are discussed.

Authentication

Enterprise Tester allows you to authenticate to the REST API via three methods:

Most users will want to use Basic Auth due to its simplicity, unless building a 3rd party add-on for Enterprise Tester. In this case we recommend the use of OAuth, so your application is not required to store user logins and passwords.

Basic Auth

Basic Auth combined with SSL will often suffice as the authentication mechanism for interacting with the Enterprise Tester API, here is an example of using Curl to retrieve a list of projects from Enterprise Tester with basic auth:

curl -u Administrator:password http://localhost/EnterpriseTester/api/project/650d8904-c145-4f7c-8b65-a02a0092a85f

In this case we are retrieving the project with ID "650d8904-c145-4f7c-8b65-a02a0092a85f" with the login "Administrator" and the password "password".

OAuth 1.0

Enterprise Tester supports OAuth 1.0a.

Implementing an OAuth 1.0a client is outside the scope of this help topic, but the key things required to establish the connection are:

Get Request Token Url

http://localhost/EnterpriseTester/OAuth/Token/GetRequestToken.rails

This is Url that you can retrieve the request token from.

User Authorization Url

http://localhost/EnterpriseTester/OAuth/Authorization/PromptForAuthorization.rails

This is the Url that you send users to, so they can authorize the request for access.

Get AccessToken Url

http://localhost/EnterpriseTester/OAuth/Token/GetAccessToken.rails

This is the Url used to exchange the request token for the access token that you can use to sign all your API requests.

For more information on the mechanics of signing a request with your access token, we recommend that you read through a tutorial on the basic authentication flow in OAuth 1.0, and then subsequently through the specification.

Bulk Actions

Overview

Bulk actions are a common extension point within Enterprise Tester, exposed as features of the grid (normally a button, or selection field and button combination).

Bulk actions can be invoked asynchronously by issuing a POST request to the backgroundtasks collection resource, with the configuration information including the command being invoked passed in the Parameters collection, as show in the example below:

{
  "Type": "bulkaction",
  "Parameters": {
    "commandName": "BulkCopy",
    "scenarioName": "BulkCopyScriptsScenario",
    "targetId": "ab1bd3c3-f30b-43b2-82e2-a07e0133511c",
    "targetType": "TestScriptPackage",
    "targetPackageId": "ab1bd3c3-f30b-43b2-82e2-a07e0133511c",
    "sourcePackageId": "4016f35b-817f-459e-8533-9fc8015335c8",
    "projectId": "c651ed19-5375-475a-a539-9f6401467130",
    "selections":[
        {"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"},
        {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"TestScript"}
    ],
    "retainStructure":true
  }
}

If we pull apart the above request we can see that we are:

Available commands

CSV Export command

The CSV Export command is an example of an action which has a payload (an exported file) which you can download after completing the action - first, here is an example of a CSV export task being created:

{
  "Type": "bulkaction",
  "Parameters": {
    "scenarioName": "CSV",
    "encoding": "UTF8",
    "delimiter": "comma",
    "onlyVisibleColumns": false,
    "includeHeader": true,
    "includeSteps": true,
    "includeStepsResults": true,
    "query": "Name ~ export",
    "exportAll": true,
    "commandName": "Export"
  }
}

As a result of creating this task, the response will indicate where the task updates can be fetched from via GET using the "Self" URL:

{   
  "Complete": false,
  "TotalElements": 0,
  "ProcessedElements": 0,
  "StartedAt": "2012-07-03T12:16:30Z",
  "ProgressInPercent": 0.0,
  "Id": "bulkaction_Export_CSV_56065c63-cdf7-4285-ab10-321646317be8",
  "Message": null,
  "Self": "http://localhost:29840/api/backgroundtask/bulkaction_Export_CSV_56065c63-cdf7-4285-ab10-321646317be8"
}

When the task has completed, fetching the task will include in it's response details of the where you can then download the exported file from (indicated in the "exportedfile" link).

{
  "Complete": true,
  "StartedAt": "2012-07-03T12:16:30Z",
  "FinishedAt": "2012-07-03T12:16:30Z",
  "ProgressInPercent": 1.0,
  "Id": "bulkaction_Export_CSV_56065c63-cdf7-4285-ab10-321646317be8",
  "Message": "Completed",
  "TotalTimeToExecute": "0s",
  "FileName": "export-Entities-2012-07-04-121630am.csv",
  "ContentType": "text/csv",
  "Encoding": "UTF8",
  "Self": "http://localhost:29840/api/backgroundtask/bulkaction_Export_CSV_56065c63-cdf7-4285-ab10-321646317be8",
  "Links": [
    {
      "Href": "http://localhost:29840/api/exportfile/export-Entities-2012-07-04-121630am.csv",
      "Rel": "exportedfile"
    }
  ]
}

Bulk Assign

This command only processes the entities specified in the 'selections' parameter

Parameter Description
action.UserId Id of the user to assign the selections to
commandName Must be set to value 'BulkAssign'
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
selections Array of ID/Type objects i.e. [{"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"}, {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"AgileRun"}] which the bulk action will operate on
targetPackageId Id of the target package (if any, normally same as the targetId)

Scenarios

Scenario "AssignBulkActionScenario"

Supported Types: Requirement, Incident, Script, AutomatedTest, ScriptAssignment, AutomatedTestAssignment, AgileRun

This scenario has scenario-specific parameters:

Parameter Description
scenarioName Must be set to value 'AssignBulkActionScenario'

Bulk Copy

This command only processes the entities specified in the 'selections' parameter

Parameter Description
commandName Must be set to value 'BulkCopy'
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
selections Array of ID/Type objects i.e. [{"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"}, {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"AgileRun"}] which the bulk action will operate on
sourcePackageId unique identifier of the source package
targetId target identifier (unique identifier of the target for this operation, normally a package or parent requirement)
targetPackageId Id of the target package (if any, normally same as the targetId)
targetType The entity type of the target (any valid TQL entity type)

Scenarios

Scenario "BulkCopyAssignmentsScenario"

Supported Types: ScriptAssignment, AutomatedTestAssignment, AgileRun

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkCopyAssignmentsScenario'

Scenario "BulkCopyRequirementsScenario"

Supported Types: Requirement

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkCopyRequirementsScenario'

Scenario "BulkCopyScriptsScenario"

Supported Types: Script, AutomatedTest

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkCopyScriptsScenario'

Bulk Create Assignments

This command only processes the entities specified in the 'selections' parameter

Parameter Description
commandName Must be set to value 'BulkCreateAssignments'
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
selections Array of ID/Type objects i.e. [{"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"}, {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"AgileRun"}] which the bulk action will operate on
sourcePackageId unique identifier of the source package
targetId target identifier (unique identifier of the target for this operation, normally a package or parent requirement)
targetPackageId Id of the target package (if any, normally same as the targetId)
targetType The entity type of the target (any valid TQL entity type)

Scenarios

Scenario "BulkCreateScriptAssignmentsScenario"

Supported Types: Script, AutomatedTest

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkCreateScriptAssignmentsScenario'

Bulk Create Scripts

This command only processes the entities specified in the 'selections' parameter

Parameter Description
commandName Must be set to value 'BulkCreateScripts'
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
selections Array of ID/Type objects i.e. [{"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"}, {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"AgileRun"}] which the bulk action will operate on
sourcePackageId unique identifier of the source package
targetId target identifier (unique identifier of the target for this operation, normally a package or parent requirement)
targetPackageId Id of the target package (if any, normally same as the targetId)
targetType The entity type of the target (any valid TQL entity type)

Scenarios

Scenario "BulkCreateScriptsScenario"

Supported Types: Requirement

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkCreateScriptsScenario'

Bulk Create Scripts From Agile Runs

This command only processes the entities specified in the 'selections' parameter

Parameter Description
commandName Must be set to value 'BulkCreateScriptsFromAgileRuns'
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
selections Array of ID/Type objects i.e. [{"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"}, {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"AgileRun"}] which the bulk action will operate on
sourcePackageId unique identifier of the source package
targetId target identifier (unique identifier of the target for this operation, normally a package or parent requirement)
targetPackageId Id of the target package (if any, normally same as the targetId)
targetType The entity type of the target (any valid TQL entity type)

Scenarios

Scenario "BulkCreateScriptsFromAgileRunsScenario"

Supported Types: AgileRun

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkCreateScriptsFromAgileRunsScenario'

Bulk Delete

This command only processes the entities specified in the 'selections' parameter

Parameter Description
commandName Must be set to value 'BulkDelete'
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
selections Array of ID/Type objects i.e. [{"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"}, {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"AgileRun"}] which the bulk action will operate on
targetPackageId Id of the target package (if any, normally same as the targetId)

Scenarios

Scenario "BulkDelete"

Supported Types: Requirement, Script, Incident, AutomatedTest, ScriptAssignment, AutomatedTestAssignment, RequirementPackage, ScriptPackage, ExecutionPackage, AgileRun, ScriptRun, AutomatedTestRun

This scenario has scenario-specific parameters:

Parameter Description
scenarioName Must be set to value 'BulkDelete'

Bulk Move

This command only processes the entities specified in the 'selections' parameter

Parameter Description
commandName Must be set to value 'BulkMove'
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
selections Array of ID/Type objects i.e. [{"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"}, {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"AgileRun"}] which the bulk action will operate on
sourcePackageId unique identifier of the source package
targetId target identifier (unique identifier of the target for this operation, normally a package or parent requirement)
targetPackageId Id of the target package (if any, normally same as the targetId)
targetType The entity type of the target (any valid TQL entity type)

Scenarios

Scenario "BulkMoveAssignmentsScenario"

Supported Types: ScriptAssignment, AutomatedTestAssignment, AgileRun

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkMoveAssignmentsScenario'

Scenario "BulkMoveRequirementsScenario"

Supported Types: Requirement

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkMoveRequirementsScenario'

Scenario "BulkMoveScriptsScenario"

Supported Types: Script, AutomatedTest

This scenario has scenario-specific parameters:

Parameter Description
removeEmptyPackages Remove empty source packages (true/false)
retainStructure Retain structure for selected items based on package structure relative to the source package (true/false)
scenarioName Must be set to value 'BulkMoveScriptsScenario'

Export

This command does not only process the selected entities, this is normally indicative of a bulk action which supports being passed a TQL query which forms the basis of entities it should apply to.

Parameter Description
columns The columns to export (if export all is set to false, this is an array of columns states i.e. [{ "Name": "col1", "IsVisible": true }, { "Name": "col2", "IsVisible": true }] )
commandName Must be set to value 'Export'
exportAll Export all records (true/false)
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
targetPackageId Id of the target package (if any, normally same as the targetId)

Scenarios

Scenario "CSV"

Supported Types: Requirement, Script, Incident, AutomatedTest, ScriptAssignment, AutomatedTestAssignment, RequirementPackage, ScriptPackage, ExecutionPackage, AgileRun

This scenario has scenario-specific parameters:

Parameter Description
delimiter The CSV delimiter to use (valid values are 'comma', 'colon', 'pipe', 'semicolon' or 'tab')
encoding The exporting enncoding type
includeAssociatedLinks Boolean value, if true then association columns (Associated requirements, Associated Scripts, Associated Incidents, External Identifiers) will include hyperlinks to the associated entities
includeAttachmentsLinks If true, then include attachment URL links in the generated output (otherwise just include attachment names)
includeHeader Include headers in export file
includeSteps Include steps for scripts
includeStepsResults Include step results for script assignments
onlyVisibleColumns Only export the visible columns
query The TQL query used to filter the items being exported to CSV
scenarioName Must be set to value 'CSV'

Traceability

This command does not only process the selected entities, this is normally indicative of a bulk action which supports being passed a TQL query which forms the basis of entities it should apply to.

Parameter Description
columns The columns to export (if export all is set to false, this is an array of columns states i.e. [{ "Name": "col1", "IsVisible": true }, { "Name": "col2", "IsVisible": true }] )
commandName Must be set to value 'Traceability'
exportAll Export all records (true/false)
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
targetPackageId Id of the target package (if any, normally same as the targetId)

Scenarios

Scenario "CSV"

Supported Types: Requirement

This scenario has scenario-specific parameters:

Parameter Description
additionalcolumns The additional columns to be included (these columns don't necessarily have to be in-scope for the entity type defined by the query / current context).
delimiter The CSV delimiter to use (valid values are 'comma', 'colon', 'pipe', 'semicolon' or 'tab')
encoding The exporting enncoding type
entitiesToInclude List of entity types to include
includeAllRuns Value specifying of either all runs or last of script are traced (All or LastRun)
includeAssociatedLinks Boolean value, if true then association columns (Associated requirements, Associated Scripts, Associated Incidents, External Identifiers) will include hyperlinks to the associated entities
includeAttachmentsLinks If true, then include attachment URL links in the generated output (otherwise just include attachment names)
includeHeader Include headers in export file
query The TQL query used to filter the root items being included in the traceability report CSV output
scenarioName Must be set to value 'CSV'

Update Script Statuses

This command only processes the entities specified in the 'selections' parameter

Parameter Description
action.Status The status to update the script to (supported statuses are 'In Progress' and 'Passed')
commandName Must be set to value 'UpdateScriptStatuses'
projectId Id of the the project the action applies to (used by some actions to determine the custom fields & permissions required to complete the action)
selections Array of ID/Type objects i.e. [{"Id":"0a02cb6d-4afa-463c-a6df-9fe400b7d8fc","Type":"TestScript"}, {"Id":"0a675d09-78cd-463e-a600-9fc80153481b","Type":"AgileRun"}] which the bulk action will operate on
targetPackageId Id of the target package (if any, normally same as the targetId)

Scenarios

Scenario "UpdateScriptStatusBulkActionScenario"

Supported Types: ScriptAssignment

This scenario has scenario-specific parameters:

Parameter Description
scenarioName Must be set to value 'UpdateScriptStatusBulkActionScenario'

Consistency

By default API methods that change data in Enterprise Tester will attempt to wait until those changes have also been reflected in the indexes (such as the Run or Entity index).

If you are performing bulk insert operations, and do not rely on needing to be able to immediately query via TQL and retrieve acurate results based on the the data that was created, updated or deleted then you can choose to "opt out" of this wait mechanism.

To do so you request must either:

If the query parameter or header is not present, or set to true, then the default behavior of waiting until the entity is indexed after persisting any changes will apply.

CORS (Cross-origin resource sharing)

CORS (Cross-origin resource sharing) is a web browser specification that defines a way for a web browser and web client to interact in such a way that cross-origin (requests to a server in a different domain) are allowed, for all HTTP methods.

Support for CORS in Enterprise Tester was introduced in version 4.4 and above, and currently supports:

Because a web browser and it's scripts are inherently insecure to the operator (the user operating the browser can see the javascript/html in raw form easily) - when using CORS with Basic Auth we strongly advise against storing the ET login and password credentials in javascript, and instead they should be retrieved from the user interactively and not stored.

And as always, when using basic Auth, we recommend you access Enterprise Tester via HTTPS (SSL).

Examples of using CORS with Enterprise Tester can be found in the CORS Examples section of our API Github Repository.

Debugging

When debugging output from the API, it can often be useful to have the JSON output rendered in an indented human-readable fashion.

To do this you use the indent-json option - passed as either a query string value e.g.

Alternatively, you can also pass it as a request header (this is the method we recommend) using the same name and/or value as for the query string.

In responses where the indent-json option is set, a response header will be set with the name indent-json and a value of true.

Examples

Non-indented output

{"Items":[{"Id":"7c67b3bf-2c6d-4dfb-a840-a14300faac14","DisplayName":"Resources","Key":"/Resources","Name":"Resources","Children":[{"Id":"fd4f34f4-8...

Indented output (using indent-json option)

{
  "Items": [
    {
      "Id": "7c67b3bf-2c6d-4dfb-a840-a14300faac14",
      "DisplayName": "Resources",
      "Key": "/Resources",
      "Name": "Resources",
      "Children": [
        {
          "Id": "fd4f34f4-8540-47c9-a994-a14300faac18",
          ...

Expand

Overview

The Enterprise Tester REST API makes extensive use of a feature called Expand (also known as Expansions) - resources that support expanding will return the list of available expansions in a property of the representation, called "Expand" - here is an example of a "project" resource with a set of available expand values:

{
  "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Name": "Test Project",
  "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Expands": [
    "Statuses",
    "Priorities",
    "RequirementTypes",
    "RequirementStatuses",
    "RequirementDifficulties",
    "IncidentTypes",
    "TestTypes",
    "IncidentResolutions",
    "IncidentStatuses",
    "Versions",
    "Components",
    "ExecutionPackages",
    "ScriptPackages",
    "RequirementPackages"
  ]
}

When making a request, you can include a query parameter called $expand that provides a comma separated list of expands you wish to have expanded in the response - so for example, to get the priority and status picklists back with the project, you would use a request like this:

GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=Status,Priority

In the response those properties will be expanded, and will no longer be listed in the "Expands" property as available properties to expand.

{
  "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Name": "Test Project",
  "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Expands": [
    "RequirementTypes",
    "RequirementStatuses",
    "RequirementDifficulties",
    "IncidentTypes",
    "TestTypes",
    "IncidentResolutions",
    "IncidentStatuses",
    "Versions",
    "Components",
    "ExecutionPackages",
    "ScriptPackages",
    "RequirementPackages"
  ],
  "Priorities": [
    {
      "Id": "6b1e46f4-8b59-4dc3-8ed1-0b3b89612e34",
      "Text": "Low",
      "SortOrder": 1,
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/priority/6b1e46f4-8b59-4dc3-8ed1-0b3b89612e34"
    },
    {
      "Id": "5d37d6a1-6b1d-4007-8fcf-2c5296af3740",
      "Text": "High",
      "SortOrder": 2,
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/priority/5d37d6a1-6b1d-4007-8fcf-2c5296af3740"
    }
  ],
  "Statuses": [
    {
      "Id": "753387d7-0a67-45bd-8b96-a58791c283bb",
      "Text": "Draft",
      "SortOrder": 1,
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/status/753387d7-0a67-45bd-8b96-a58791c283bb"
    },
    {
      "Id": "023b39dc-31a3-4bb6-bf01-69da23de5d3f",
      "Text": "Final",
      "SortOrder": 2,
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/status/023b39dc-31a3-4bb6-bf01-69da23de5d3f"
    }
  ]
}

Expansions can be more than one level deep. Here is an example of getting a project, with its top level requirement package expanded, and each of those packages children collection expanded as well.

We do this by using a period (.) to navigate to the child expansion:

GET /api/project/593c2fb5-2300-4bce-ad50-9f07009b207c?$expand=RequirementPackages.Children

As you can see the child packages are then expanded as well:

{ 
"Expands" : [ "Components",  ...  ],
  "Id" : "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Name" : "Test Project",
  "Self" : "/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "RequirementPackages" : [{       
      "Id" : "d2353811-36f5-45cf-bb72-a0440092ab60",
      "Name" : "Requirements",
      "OrderNumber" : 0,
      "Parent" : null,
      "Self" : "http://localhost/api/requirementpackage/d2353811-36f5-45cf-bb72-a0440092ab60"
      "Children" : [ 
            {
              "Expands" : [ "Children", "Parent" ],
              "Id" : "87fcdd47-c8b5-4eb0-867b-a0440092ba61",
              "Name" : "Traceability Matrix",
              "OrderNumber" : 0,
              "Self" : "http://localhost/api/requirementpackage/87fcdd47-c8b5-4eb0-867b-a0440092ba61"
            },
            {
              "Expands" : [ "Children", "Parent" ],
              "Id" : "ef3882a8-27b3-4a0c-9d54-a0440092bb81",
              "Name" : "Business Requirements",
              "OrderNumber" : 0,
              "Self" : "http://localhost/api/requirementpackage/ef3882a8-27b3-4a0c-9d54-a0440092bb81"
            },
            {
              "Expands" : [ "Children", "Parent" ],
              "Id" : "7998df31-147d-4954-b6b6-a0440092bb8a",
              "Name" : "Stakeholder Requirements",
              "OrderNumber" : 0,
              "Self" : "http://localhost/api/requirementpackage/7998df31-147d-4954-b6b6-a0440092bb8a"
            },
            {
              "Expands" : [ "Children", "Parent" ],
              "Id" : "f2a2c9ad-98c6-480c-b925-a0440092bbe9",
              "Name" : "Non-Functional Requirements",
              "OrderNumber" : 0,
              "Self" : "http://localhost/api/requirementpackage/f2a2c9ad-98c6-480c-b925-a0440092bbe9"
            }
          ],
      "Expands" : [ "Parent" ],
  }]  
}

For each method supported by a resource (GET, POST, PUT) documented within the help system, we also include details of the available expansions.

Deep Expansion

You are not limited to expanding to one or two levels - to expand many levels of depth, you can continue to use a period character between each level i.e. RequirementPackages.Children. Children will return the requirement package, with its children and those children's children.

GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=RequirementPackages.Children.Children

As we can see the multiple levels are expanded as requested:

{
  "Id": "c651ed19-5375-475a-a539-9f6401467130",
  "Name": "Test Project",
  "OrganisationId": "564a2bed-e152-4e58-a57d-9f4100888460",
  "OrganisationName": "Acme Inc",
  "Description": "Description of project",
  "EstimatedEndDate": "2011-09-29T11:00:00Z", 
  "Slug": "test-project",
  "AutoNumberRequirements": true,
  "AutoNumberScripts": true,
  "StartDate": "2011-08-14T12:00:00Z",
  "Expands": [
    "Components",
    "ExecutionPackages",
    "IncidentResolutions",
    "IncidentStatuses",
    "IncidentTypes",
    "Priorities",
    "RequirementDifficulties",
    "RequirementStatuses",
    "RequirementTypes",
    "ScriptPackages",
    "Statuses",
    "TestTypes",
    "TimeTrackingConfiguration",
    "Versions"
  ],
  "RequirementPackages": [
    {
      "Id": "53b483c7-e332-4d38-bf86-9fd700d552d2",
      "ProjectId": "c651ed19-5375-475a-a539-9f6401467130",
      "Name": "Requirements",
      "OrderNumber": 0,
      "Expands": [
        "Parent",
        "Project",
        "Requirements"
      ],
      "Children": [{
        "Id": "f3b483c7-e332-4d38-bf86-9fd700d552d2",
        "ProjectId": "c651ed19-5375-475a-a539-9f6401467130",
        "ParentId": "53b483c7-e332-4d38-bf86-9fd700d552d2",
        "Name": "Reports",
        "OrderNumber": 0,
        "Expands": [
          "Parent",
          "Project",
        "Children": [...],
        ],
        "Self": "http://localhost:29840/api/requirementpackage/f3b483c7-e332-4d38-bf86-9fd700d552d2"
      }],
      "Self": "http://localhost:29840/api/requirementpackage/53b483c7-e332-4d38-bf86-9fd700d552d2"
    }
  ],
  "Self": "http://localhost:29840/api/project/c651ed19-5375-475a-a539-9f6401467130"
}

'All' Expansion

When exploring the API it can be useful to expand everything, so you can see what information is available - this can be done through the pseudo-expansion "All" i.e.

GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=All

This will automatically be replaced with all available expands in the response:

{
  "Id": "53b483c7-e332-4d38-bf86-9fd700d552d2",
  "ProjectId": "c651ed19-5375-475a-a539-9f6401467130",
  "Name": "Requirements",
  "OrderNumber": 0,
  "Children": [...],
  "Parent": null,
  "Project": {...},
  "Requirements": [...],
  "Self": "http://localhost:29840/api/requirementpackage/53b483c7-e332-4d38-bf86-9fd700d552d2"
}

You can use multiple levels of "All" as well - but we strongly advise against using "All" when writing code that interacts with the API as it will cause very large payloads to be returned and negatively impact on the performance of Enterprise Tester.

FieldValues

Overview

Each resource that supports custom fields (incident, scriptrun, requirement, script) has an optional expand called "FieldValues". FieldValues is an object with properties for each custom field and values representing the values for that type of custom field.

Here is an example of a FieldValues expand:

{
    //...
    "FieldValues": {
         "SourceCustom": "src/customer/something.js",
         "ScriptRunBuildNumber": "24876",
     }
}

Single Valued Fields

For single valued custom field types (e.g. text,date, checkbox, hyperlink) the property name is the name of the custom field and the value is the JSON encoded value of that custom field value. e.g.

{
    //...
    "FieldValues": {
         "customdate": "2013-06-17T12:00:00Z",
         "customhyperlink": "http://google.com",
         "customnumber": 12,
     }
}

Picklist Fields

For custom field types which represent picklist value/s (Combo Box, Checkbox Group, Radio Group and Multi Select) things are slightly different. When you GET the resource the Id and Text of the picklist value is returned. (To get a list of valid picklist values for the custom field you can use the customfield/{name}?$expand=Options resource.)

For a Combo Box field you might get:

{
    //...
    "FieldValues": {
         "Automation_System": {
             "Id": "f13e6fbb-c1b9-49ad-b4cb-d895a9affab1",
             "Text": "Selenium Runer"
         }
     }
}

For picklists field types which support multiple values - the property is a list of Id/Text values.

A Checkbox Group field might look like:

{
    //...
    "FieldValues": {
         "ProjectCategories": [
             {
                 "Id": "8e3df968-42ad-474a-94ab-b1374174345e",
                 "Text": "Reporting"
             },
             {
                 "Id": "cb1a014d-016e-4e18-824e-ab71c33938b2",
                 "Text": "User Acceptance"
             }
         ]
     }
}

Updating Picklist FieldValues (PUT)

When you PUT picklist values - only the Id is required. This is the Id of the pick list value. The list of Ids for picklist values can be retrieved via the customfield/{name}?$expand=Options resource.

Here's an example:

Get the list of Picklist Value Ids

GET /api/customfield/Automation_System?$expand=Options

In the response we can see the "Options" expand has the list of picklist values for this custom field.

{
    "Id": "c9c0f30b-c460-47eb-a3aa-a1db00f948c1",
    "Name": "Automation_System",
    "CustomFieldTypeName": "ComboBox",
    "Label": "Automation System",
    "Description": "",
    "Required": false,
    "Entities": [
        "ScriptRun"
    ],
    "Scopes": [
        {
            "Type": "Organisation",
            "Id": "de266140-1f28-4816-bb73-a1c40106ac8d",
            "Name": "Awesome Testing services"
        }
    ],
    "Expands": [
        "Configuration",
        "Type"
    ],
    "Options": [
        {
            "Identifier": "e79ef86f-cb69-4647-9c14-52ccacdd1bec",
            "Text": "Selenium"
        },
        {
            "Identifier": "f13e6fbb-c1b9-49ad-b4cb-d895a9affab1",
            "Text": "Webdriver"
        },
        {
            "Identifier": "d1682d5c-20da-4c29-a748-133375df04e9",
            "Text": "Hand on mouse"
        }
    ],
    "Self": "http://localhost:8092/EnterpriseTester/api/customfield/Automation_SystemAutomation_System?$expand=Options",
    "Links": [
        {
            "Href": "http://localhost:8092/EnterpriseTester/api/customfieldtype/combobox",
            "Rel": "CustomFieldType"
        }
    ]
}

Update picklist values on a resource

PUT /api/scriptrun/e5e1e31f-40ba-4e87-8776-a1d300d6efd4?$expand=FieldValues

The body should look like:

{
    "Id": "e5e1e31f-40ba-4e87-8776-a1d300d6efd4",
    "ActualDuration": "",
    "ScriptId": "866bd9aa-2cd3-4127-b171-a1d300d6efd4",
    "ScriptVersion": 20,
    "AssignmentId": "866bd9aa-2cd3-4127-b171-a1d300d6efd4",
    "CreatedAt": "2013-03-20T21:45:18Z",
    "LastUpdatedAt": "2013-06-12T03:47:12Z",
    "CreatedById": "cd38e32a-adb4-42f6-a075-a1c40106d2d0",
    "CreatedBy": "Administrator",
    "RunById": "cd38e32a-adb4-42f6-a075-a1c40106d2d0",
    "RunBy": "Administrator",
    "LastUpdatedById": "cd38e32a-adb4-42f6-a075-a1c40106d2d0",
    "LastUpdatedBy": "Administrator",
    "Status": "In Progress",
    "Expands": [
        "Assignment",
        "FieldControls",
        "StepResults"
    ],
    "FieldValues": {
        "Automation_System": {
            "Id": "f13e6fbb-c1b9-49ad-b4cb-d895a9affab1"
        }
    },
    "Self": "http://localhost:8092/EnterpriseTester/api/scriptrun/e5e1e31f-40ba-4e87-8776-a1d300d6efd4"
}

Simplified syntax for PickList values

We also support shortcuts for picklist values. For single valued picklists - we support PUTs using the picklist Text or Id. For multi-valued picklists - you can supply an array of Id or Text.

e.g.

PUT /api/scriptrun/e5e1e31f-40ba-4e87-8776-a1d300d6efd4?$expand=FieldValues

With a body like

{
    //...
    "FieldValues": {
         "ProjectCategories": ["Reporting", "8e3df968-42ad-474a-94ab-b1374174345e"],
         "Automation_System": "Selenium"
     }
}

JSONP

JSON (Json with Padding) complements in the existing capability of Enterprise Tester API methods to return JSON. I provides a method to request data from the server where CORS is not a viable alternative.

In a JSONP request, the contents of the response is wrapped in a javascript function call, which allows you to fetch it with a script tag, and the have to response automatically invoke the callback once loaded, to process the response body - let's take a look at an example:

To make a JSONP request you pass an additional query parameter as part of the url with the name "callback", the value of which is the name of the callback function to invoke:

Example

If we make a request as follows:

GET http://localhost/EnterpriseTester/api/groups?callback=processResponse

Then we can see in the response, that it's wrapped in a call to the function processResponse:

processResponse({
  "Items": [
    {
      "Id": "2192ce56-971d-4b19-9df7-a0770041f1cf",
      "Name": "Viewer",
      "Description": "Viewer",
      "Expands": [
        "Users"
      ],
      "Self": "http://localhost/EnterpriseTester/api/group/2192ce56-971d-4b19-9df7-a0770041f1cf",
      "Links": [...]
    },
    ...
  ],  
  "Self": "http://localhost/EnterpriseTester/api/groups?callback=process"
})

Limitations

JSONP requests are only support for GET HTTP methods.

OData (Open Data Protocol)

Some parts of the REST API expose collections which can be queried via OData mechanisms.

ODATA, or Open Data Protocol, is an involved standard allowing for adhoc filtering, paging (and much more) of resources - more details can be found here.

Currently Enterprise Tester leverages some features of OData as below:

Enterprise Tester at current does not intend to be OData compliant, in particular we have no plans to implement the navigation or metadata features that are within OData, at least not for the first version of the API.

Please see the Uri Conventions topic on the OData website for more information on how the various query parameters can be used to compose queries.

URL structure

Just to whet your appetite, here is a simple query of the projects collection - demonstrating projects being filtered, ordered and paged:

GET /api/projects?$filter=substringof('test',Name) eq true&$orderby=Name desc&$top=5

Pulling the URL apart we can see that:

Examples

Example - Query without inline count

Url:

 http://myserver/EnterpriseTester/api/users?$filter=Name eq 'john'&$top=2

Results:

{
  "Items": [
    {
      "Id": "5b2b0ad0-5371-4abf-a661-9f410088925f",
      "UserName": "Administrator",
      "Email": "john.smith@mycompany.com",
      "FirstName": "John",
      "LastName": "Smith",
      "Self": "http://myserver/EnterpriseTester/api/user/5b2b0ad0-5371-4abf-a661-9f410088925f"
    },
    {
      "Id": "084c8a30-071c-4280-bf4c-9f48015b195f",
      "UserName": "johnb",
      "Email": "john.blogs@mycompany.com",
      "FirstName": "John",
      "LastName": "Bloggs",
      "Self": "http://myserver/EnterpriseTester/api/user/084c8a30-071c-4280-bf4c-9f48015b195f"
    }
}

Example - Query with inline count

Url:

http://myserver/EnterpriseTester/api/users?$inlinecount=allpages&$top=2&$skip=3

Results:

{
    "Skip": 3,
    "Top": 2,
    "Total": 497,
    "Items": [
        {
          "Id": "5b2b0ad0-5371-4abf-a661-9f410088925f",
          "UserName": "Administrator",
          "Email": "john.smith@mycompany.com",
          "FirstName": "John",
          "LastName": "Smith",
          "Self": "http://myserver/EnterpriseTester/api/user/5b2b0ad0-5371-4abf-a661-9f410088925f"
        },
        {
          "Id": "084c8a30-071c-4280-bf4c-9f48015b195f",
          "UserName": "johnb",
          "Email": "john.blogs@mycompany.com",
          "FirstName": "John",
          "LastName": "Bloggs",
          "Self": "http://myserver/EnterpriseTester/api/user/084c8a30-071c-4280-bf4c-9f48015b195f"
        }
    ]
}

Swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

As of version 4.8 Enterprise Tester now supports describing its API in a swagger compatible manner.

Retrieving the Swagger JSON

Swagger describes the various resources, methods and parameters of a REST API in JSON format. The swagger specification is documented here.

In Enterprise Tester the Swagger API List resource allows retrieval of the "swagger JSON" for the Enterprise Tester API.

Interacting with the API via Swagger UI

Swagger includes its own viewer called Swagger UI - which uses the Swagger JSON output to generate interactive documentation for Swagger-documented API, allowing you to easily try various API methods without requiring a client or programming skills.

Enterprise Tester includes a copy of Swagger UI with itself, you can access the client via the link:

http://{et_server_url}/content/vendor/swagger/index.html#!/api

Generating clients

There are a number of client generators for swagger - check out the Swagger website for more details.

Popular client generators such as Swagger codegen and JavaScript client Swagger-client which provide support for generating clients from Enterprise Tester's swagger JSON in languages such as Javascript, Ruby, Scala, Java, PHP and Python.

Time Zones

Introduction

By default All TQL queries are executed in the context of the servers configured time-zone.

As of version 4.6 of Enterprise Tester, we now allow the time-zone to be overriden when searching for or aggregating over date/time values (such as when grouping by day), ensuring you get the results you would expect when using the API.

The methods in which the timezone can be set are:

The query hint can be supplied by prefixing your existing query with the timezone hint, so if you had the query:

GROUP BY Day(CreatedAt) { COUNT }

You could change the timezone the query ran in by prefixing the query with SET TimeZone=;

SET TimeZone=UTC; GROUP BY Day(CreatedAt) { COUNT }

This method also allows for specifying the timezone when running queries from within the UI, which can be useful if you want to get consistent output from a saved query for all users, even if they are in different timezones.

If the timezone contains a space or punctuation character such as a forward slash, you will need to enclose it within double or single quotes e.g.

SET TimeZone="America/New_York"; GROUP BY Day(CreatedAt) { COUNT }

For more information on how SET (also known as query hints) work - see the SET topic in the TQL help section.

Browser Timezone identification

Enterprise Tester will automatically attempt to detect and use the timezone of the browser when performing searches from within the UI, this is done by using a 3rd party javascript library "jsTimezoneDetect".

If you find the results of your queries are incorrect due to mis-handling of timezone detection, currently your options are:

Timezone information for the server and client are displayed on the user-profile screen, under the "Timezone" heading, and hovering over the current time zone will display the "raw" IANA zone info key that is being passed to the Enterprise Tester server (which is then subsequently converted into a windows timezone when executing the TQL query.

Time Zone Identifiers

Enterprise Tester supports time zones specified using either the Windows Timezone ID or IANA zone info key (Olsen Timezone ID).

A list of common time zone identifiers follows:

If your timezone is not present on this list, please let us know and we will add support for it in a future version of Enterprise Tester.

TQL

Some resources in Enterprise Tester support executing TQL queries. For details on constructing a valid TQL query see the TQL Search topic.

The results of a TQL query a retrieved via a GET request to a resource, and use the following parameters.

Query Parameters

Uploading Files (Multipart MIME)

Multipart MIME is a standard used for uploading files to webservers. All the API resources which support file uploads in ET use this standard.

Uploads look like this:

POST /EnterpriseTester/api/stepresult/25eb6aa0-3514-48bf-8c59-a21200d7a6fc/attachments HTTP/1.1
Host: 127.0.0.1
Content-Type: multipart/mixed; boundary=65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Length: 3
Authorization: Basic bGFidmlldzpvbnNhbGE=

--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename="notes.txt"; name=notes; size=3
Content-Type: text/plain
Content-Length: 3

ABC
--65bf6b94-c91c-442c-abe7-f41444d7c71f--

Typically - a library will generate this for you - but if your generating it yourself then the key points are as follows:

  1. Content type set to "multipart/mixed".
  2. A "boundary=[something unique]"
  3. The boundary starts and ends the body of the POST. (with -- at the start and --[boundary]-- at the end)
  4. There must be a blank line between the headers for the part and the part content. (in the example - between Content-Length: 3 and ABC)

Overview

Widgets are used to make up the UI of edit screens for entities, and include combo boxes, text areas, radio buttons and many more UI components.

Widgets are returned from the Widgets API Resource end point or by using the "Widgets" expand when retrieving an entity or project.

All widgets share the following value/options:

PropertyTypeDescription
WidgetCategory string Either "intrinsic" or "custom", for in-built and custom widgets
Name string Name of the inbuilt or custom widget
Label string The label for the widget
WidgetType string A type-descriminator, used for determining how the widget should be rendered
ImplementationType string The handler (class) in code which is used to represent this widget, this information can be used to provide additional customisation to a widget based on what information it represents.
HandlerType string The key of the handler being used to render this widget, this information can be used to provide additional customisation to a widget based on what information it represents.
ValueType string The JSON Schema type of the value for this widget, these should be consistent with the swagger for the API.
ItemId string A unique ID assigned to some inbuilt widgets so they can be handled in special ways within the UI - for example "remote links" for a requirement will not be shown if the requirement is being created, or if it has yet to be synchronized with any remote entities, and that remote links widget is identified by it's ItemId.
Required Boolean If present, this determines if the widget is required or not. If the value is not present, the default behaviour of not-required is assumed.
ReadOnly Boolean If present, this widget is in a read-only state.
TabIndex integer Represents the tab-order of fields on screen - normally widgets are returned in-order anyway, but this can be used for explicit tab-order assignment which does not conform to field order.
Hidden Boolean If the value is present, determines if the field is current hidden or not - if not present, the field is assumed to be visible.
FormName string Generally retained for internal use by Enterprise Tester, if present, this will be the key used for the key/value pair of this widget when submitted back to the server.
Description string Description of the field (descriptions can be captured on the custom field configure screen for each custom field). Descriptions are not currently used within the Enterprise Tester UI, but are available for 3rd party tool developers.

In addition each widget may have more options configured specific to that type of field.

Note: intrinsic fields do not currently include their current value in their representation, the value is instead retrieved from the model, using the 'Name' or 'FormName' as the key.

Widgets

Assign User

The assign user field is used to pick an assignee - it makes use of the Users Search API resource to retrieve users for the picker.

Widget Type: AssignUserPicker

{
  "FieldCategory": "intrinsic",
  "Name": "AssignedTo",
  "Label": "Assigned To",
  "WidgetType": "AssignUserPicker",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.AssignededTo",
  "HandlerType": "AssignedTo",
  "ItemId": "assigned-to",
  "Required": false,
  "TabIndex": 106,
  "FormName": "requirement.AssignedTo"
}

Cascading Select

Widget Type: CascadingSelect

The cascading select is a series of 2 or more combo boxes, where selections and the first level determine what child options can be selected in the second combo etc. The number of combo-boxes requires is determined by the "Levels" property (2 in this case for the example below).

Selections are represented as an array, with the first element being the first-level section, second element being the second-level selection and so on, the field must support optional selection of second/third etc. level options.

 {
  "Levels": 2,
  "Value": [
    {
      "Identifier": "10005",
      "Text": "Level A"
    },
    {
      "Identifier": "10007",
      "Text": "Level 1"
    }
  ],
  "Options": [
    {
      "Identifier": "10005",
      "Text": "Level A",
      "Children": [
        {
          "Identifier": "10007",
          "Text": "Level 1",
          "Children": []
        },
        {
          "Identifier": "10010",
          "Text": "Level 2",
          "Children": []
        }
      ]
    },
    {
      "Identifier": "10006",
      "Text": "Level B",
      "Children": [
        {
          "Identifier": "10008",
          "Text": "Level 2",
          "Children": []
        },
        {
          "Identifier": "10009",
          "Text": "Level 1",
          "Children": []
        }
      ]
    }
  ],
  "FieldCategory": "custom",
  "Name": "Cascading",
  "Label": "Cascading`",
  "WidgetType": "CascadingSelect",
  "ImplementationType": "EnterpriseTester.Plugins.DefectTracking.Fields.DefectTrackerCascadingSelectCustomField",
  "HandlerType": "Defect Tracker Cascading Select",
  "ValueType": "IValue[]",
  "Required": false,
  "TabIndex": 117,
  "FormName": "requirement.Cascading",
  "Description": ""
}

CheckBox

Widget Type: Checkbox

{
  "Value": true,
  "FieldCategory": "custom",
  "Name": "CustomCheckBox",
  "Label": "CustomCheckBox",
  "WidgetType": "CheckBox",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.CheckboxFieldType",
  "HandlerType": "Checkbox",
  "ValueType": "Boolean",
  "Required": false,
  "TabIndex": 108,
  "FormName": "requirement.CustomCheckBox",
  "Description": ""
}

Date Picker

The date picker field expects the date to submitted as a string, conforming to the FormatString (.Net Date/Time format string). In addition the .Net date/time format string, we also include a FormatCode which is a PHP and ExtJS compatible parsing/format syntax (see the Ext.Date documentation for more details).

Widget Type: Date

{
  "FormatCode": "j/i/Y",
  "FormatString": "d/mm/yyyy",
  "FieldCategory": "custom",
  "Name": "CustomDate",
  "Label": "CustomDate",
  "WidgetType": "Date",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.DateField",
  "HandlerType": "Date",
  "ValueType": "Date",
  "Required": false,
  "TabIndex": 109,
  "FormName": "requirement.CustomDate",
  "Description": ""
}

External Comments

Widget Type: RequirementExternalComments

{
  "FieldCategory": "intrinsic",
  "Name": "ExternalComments",
  "Label": "External Comments",
  "WidgetType": "RequirementExternalComments",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.RequirementExternalComments",
  "HandlerType": "RequirementExternalComments",
  "ItemId": "requirementcommentsgrid",
  "Required": false,
  "ReadOnly": true,
  "TabIndex": 109
}

External Links

Widget Type: ExternalLinks

{
  "FieldCategory": "intrinsic",
  "Name": "ExternalLinks",
  "Label": "External Links",
  "WidgetType": "ExternalLinks",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.ExternalLinksGrid",
  "HandlerType": "ExternalLinksGrid",
  "ItemId": "externallinksgrid",
  "Required": false,
  "ReadOnly": true,
  "TabIndex": 110
}

Html Editor

Widget Type: HtmlEditor

{
  "Value": "<b><font color=\"#ff0000\">​Hello world</font></b>",
  "FieldCategory": "custom",
  "Name": "CustomRichText",
  "Label": "CustomRichText",
  "WidgetType": "HtmlEditor",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.RichTextField",
  "HandlerType": "RichText",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 114,
  "FormName": "requirement.CustomRichText",
  "Description": ""
}

Label

Widget Type: Label

This component is used for rendering a read-only text widget.

{
  "FieldCategory": "intrinsic",
  "Name": "CreatedBy",
  "Label": "Raised By",
  "WidgetType": "Label",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.Label",
  "HandlerType": "Label",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 102,
  "FormName": "incident.CreatedBy",
  "Value": "Joe Blogs (joeb)"
}

Multi Select

Widget Type(s): CheckBoxGroup, MultiSelect

{
  "Values": [
    "911d5b79-cdf2-477e-ae36-2fb4a0afa2b9",
    "cb3459de-f3a2-4ce5-bb54-25cb20778d5d"
  ],
  "Options": [
    {
      "Identifier": "911d5b79-cdf2-477e-ae36-2fb4a0afa2b9",
      "Text": "A"
    },
    {
      "Identifier": "ad0b2fc6-be31-4be8-83b4-c32ff12e50b6",
      "Text": "B"
    },
    {
      "Identifier": "cb3459de-f3a2-4ce5-bb54-25cb20778d5d",
      "Text": "C"
    }
  ],
  "FieldCategory": "custom",
  "Name": "CustomMultiSelect",
  "Label": "CustomMultiSelect",
  "WidgetType": "MultiSelect",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.MultiSelectField",
  "HandlerType": "MultiSelect",
  "ValueType": "String[]",
  "Required": false,
  "TabIndex": 107,
  "FormName": "requirement.CustomMultiSelect",
  "Description": ""
}

Multi-line Text Area

Widget Type: TextArea

{
  "Value": "This is line 1\nThis is line 2",
  "FieldCategory": "custom",
  "Name": "CustomTextArea",
  "Label": "CustomTextArea",
  "WidgetType": "TextArea",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.TextAreaField",
  "HandlerType": "TextArea",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 105,
  "FormName": "requirement.CustomTextArea",
  "Description": ""
}

Single Select

Widget Type(s): ComboBox, RadioGroup

{
  "Value": "9bf6adcd-d3de-4e0f-b794-1fc898cf0fa4",
  "Options": [
    {
      "Identifier": "9bf6adcd-d3de-4e0f-b794-1fc898cf0fa4",
      "Text": "A"
    },
    {
      "Identifier": "536e8f83-6c4a-4bbd-bd1d-e9c81071f190",
      "Text": "B"
    },
    {
      "Identifier": "bcf55fd1-3f85-4f21-b316-afc5bd085e0f",
      "Text": "C"
    }
  ],
  "FieldCategory": "custom",
  "Name": "CustomComboBox",
  "Label": "CustomComboBox",
  "WidgetType": "ComboBox",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.ComboBoxField",
  "HandlerType": "ComboBox",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 106,
  "FormName": "requirement.CustomComboBox",
  "Description": ""
}

Single-line Text widget

Widget Type: Text

{
  "Value": "Hello world",
  "MinLength": 1,
  "MaxLength": 1024,
  "MaxLengthText": "Field must be between 1 and 1024 characters long",
  "MinLengthText": "Field must be between 1 and 1024 characters long",
  "FieldCategory": "custom",
  "Name": "CustomText",
  "Label": "CustomText",
  "WidgetType": "Text",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.TextField",
  "HandlerType": "Text",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 104,
  "FormName": "requirement.CustomText",
  "Description": "",
  "EmptyText": "Please enter some text"
}

Time Span

Time span fields are rendered using the text widget - to provide an alternative representation of this field in your own tool, use the HandlerType or ImplementationType to detect the presence of the estimated or actual duration fields:

Widget Type: Text

{
  "EmptyText": "eg. 4d, 5h 30m",
  "FieldCategory": "intrinsic",
  "Name": "EstimatedDuration",
  "Label": "Est. Duration",
  "WidgetType": "Text",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.EstimatedDuration",
  "HandlerType": "EstimatedDuration",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 105,
  "FormName": "requirement.EstimatedDurationString"
}

Permissions

The account accessing the API requires project/organisation level permissions to access each supported Method of a resource, the table below documents each resource and the permissions required for use.

NameGETPATCHPOSTPUTDELETE
TestManagement / ViewUnsupportedUnsupportedTestManagement / ExecuteTestsTestManagement / ManageExecution
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedTestManagement / ExecuteTests
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
UnsupportedUnsupportedUnsupportedUnsupportedTestManagement / ExecuteTests
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
No PermissionsUnsupportedNo PermissionsUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ManageScriptsTestManagement / ManageScripts
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ManageExecutionTestManagement / ManageExecution
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageExecutionUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedTestManagement / ManageExecution
UnsupportedUnsupportedUnsupportedUnsupportedTestManagement / ManageExecution
TestManagement / ViewUnsupportedTestManagement / ManageExecutionUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedTestManagement / ManageExecution
TestManagement / ViewUnsupportedTestManagement / ManageExecutionUnsupportedUnsupported
UnsupportedUnsupportedUnsupportedUnsupportedTestManagement / ManageExecution
TestManagement / ViewUnsupportedTestManagement / ManageExecutionUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewTestManagement / ExecuteTestsUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedNo PermissionsNo Permissions
No PermissionsNo PermissionsUnsupportedNo PermissionsNo Permissions
No PermissionsUnsupportedNo PermissionsUnsupportedUnsupported
Resources / ExternalLinksResources / ExternalLinksUnsupportedResources / ExternalLinksResources / ExternalLinks
UnsupportedUnsupportedResources / ExternalLinksUnsupportedUnsupported
Resources / ExternalLinksUnsupportedResources / ExternalLinksUnsupportedUnsupported
No PermissionsUnsupportedNo PermissionsUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageScriptsUnsupportedUnsupported
Enforced by task implementationUnsupportedUnsupportedUnsupportedUnsupported
UnsupportedUnsupportedEnforced by task implementationUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ManageExecutionTestManagement / ManageExecution
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageExecutionUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
Resources / ExternalLinksResources / ExternalLinksUnsupportedResources / ExternalLinksResources / ExternalLinks
Resources / ExternalLinksResources / ExternalLinksUnsupportedUnsupportedResources / ExternalLinks
UnsupportedUnsupportedResources / ExternalLinksUnsupportedUnsupported
Resources / ExternalLinksUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
UnsupportedUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
Resources / ExternalLinksUnsupportedResources / ExternalLinksUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ViewUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
Resources / ExternalLinksUnsupportedResources / ExternalLinksUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
UnsupportedUnsupportedNo PermissionsUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedNo PermissionsUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityAdministration / Organisation / ManageUserAndGroupSecurity
Administration / Organisation / ManageUserAndGroupSecurityUnsupportedUnsupportedUnsupportedUnsupported
Administration / Organisation / ManageUserAndGroupSecurityUnsupportedUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityUnsupported
No PermissionsUnsupportedUnsupportedNo PermissionsUnsupported
No PermissionsUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ViewUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ExecuteTestsTestManagement / ExecuteTests
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
UnsupportedUnsupportedUnsupportedUnsupportedTestManagement / ExecuteTests
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
Administration / OrganisationUnsupportedUnsupportedUnsupportedUnsupported
Administration / OrganisationUnsupportedUnsupportedUnsupportedUnsupported
Administration / OrganisationUnsupportedUnsupportedAdministration / OrganisationUnsupported
No PermissionsNo PermissionsUnsupportedUnsupportedNo Permissions
No PermissionsUnsupportedAdministration / OrganisationUnsupportedNo Permissions
No PermissionsUnsupportedUnsupportedAdministration / Organisation / ManageOrganisationAdministration / Organisation / ManageOrganisation
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ViewUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedAdministration / Organisation / ManageOrganisationUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedProject / ManageProjectProject / ManageProject
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedAdministration / Organisation / ManageOrganisationUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedAdministration / Organisation / ManageOrganisationAdministration / Organisation / ManageOrganisation
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
Administration / Organisation / ManageUserAndGroupSecurityUnsupportedUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ViewUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
Administration / Organisation / ManageUserAndGroupSecurityUnsupportedUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityUnsupported
TestManagement / ViewUnsupportedProject / ManageProjectUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ViewUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ViewTestManagement / View
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
UnsupportedUnsupportedTestManagement / ViewUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ManageRequirementsTestManagement / ManageRequirements
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
UnsupportedUnsupportedUnsupportedUnsupportedTestManagement / ManageRequirements
TestManagement / ViewUnsupportedTestManagement / ManageRequirementsUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ManageRequirementsTestManagement / ManageRequirements
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageRequirementsUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageRequirementsUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ManageScriptsTestManagement / ManageScripts
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ManageExecutionTestManagement / ManageExecution
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageExecutionUnsupportedUnsupported
UnsupportedUnsupportedUnsupportedUnsupportedTestManagement / ExecuteTests
TestManagement / ViewUnsupportedTestManagement / ManageScriptsUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ManageScriptsTestManagement / ManageScripts
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageScriptsUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedTestManagement / ExecuteTestsTestManagement / ManageExecution
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageScriptsUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageExecutionUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ViewUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedUnsupported
UnsupportedUnsupportedUnsupportedUnsupportedTestManagement / ExecuteTests
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
TestManagement / ViewUnsupportedUnsupportedUnsupportedTestManagement / ExecuteTests
TestManagement / ViewUnsupportedTestManagement / ExecuteTestsUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
Resources / ExternalLinksResources / ExternalLinksUnsupportedResources / ExternalLinksResources / ExternalLinks
UnsupportedUnsupportedResources / ExternalLinksUnsupportedUnsupported
Resources / ExternalLinksUnsupportedResources / ExternalLinksUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedNo Permissions
No PermissionsUnsupportedAdministrationUnsupportedNo Permissions
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedNo PermissionsUnsupportedUnsupported
UnsupportedUnsupportedUnsupportedUnsupportedNo Permissions
UnsupportedUnsupportedNo PermissionsUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ManageExecutionUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityAdministration / Organisation / ManageUserAndGroupSecurity
No PermissionsUnsupportedUnsupportedNo PermissionsUnsupported
UnsupportedUnsupportedAdministration / OrganisationUnsupportedUnsupported
UnsupportedUnsupportedUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityUnsupported
Administration / Organisation / ManageUserAndGroupSecurityUnsupportedUnsupportedUnsupportedUnsupported
Administration / Organisation / ManageUserAndGroupSecurityUnsupportedUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityUnsupported
No PermissionsUnsupportedAdministration / Organisation / ManageUserAndGroupSecurityUnsupportedUnsupported
TestManagement / ViewUnsupportedTestManagement / ViewUnsupportedUnsupported
No PermissionsUnsupportedUnsupportedUnsupportedUnsupported

Resources

Enterprise Tester's REST API is composed of a number of resources.

Resource: Agile Run ( /api/agilerun/{id} )

Agile Run resource representing an agile run entity with Enterprise Tester, this resource allows you to fetch, update and delete existing runs within an Execution Package.

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Removes an agile run.

Required Permissions

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
200 - OKReturned if agile run was successfully deleted.

Example - DELETE

Example of deleting an agile run via DELETE.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of Agile Run to delete.

Status Code

200 - OK

GET


Retrieves a single agile run by its GUID Identifier.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if request is completed successfully.
403 - ForbiddenReturned if request can not be completed due to lack of permissions or validation problems.
404 - NotFoundReturned if agile run does not exist.

Example - GET

Example of retrieving an agile run by its unique GUID Identifier.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of the Agile Run to fetch.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Description": null,
  "Name": "Agile Run Started At 2-05-2012 10:00:08 p.m.",
  "Notes": null,
  "Number": 1,
  "Objective": null,
  "PostCondition": null,
  "PreCondition": null,
  "PriorityId": "a79e5778-befc-4ffe-b910-873ff737296c",
  "StatusId": "f304c468-58d4-4245-a9c8-7b61a42f57f3",
  "TypeId": "27537607-6c59-4d7c-b812-d5dff13ff738",
  "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25",
  "OrderNumber": 0,
  "ProjectId": "ef7b7b88-b990-4cb9-98b5-2d89786e51f3",
  "ProjectName": "Test Project",
  "PackageName": "Execution Sets",
  "EstimatedDuration": null,
  "ActualDuration": null,
  "ExecutionStatus": "Not Run",
  "AgileRunNumberReadOnly": false,
  "Expands": [
    "Widgets",
    "FieldValues"
  ],
  "Steps": [
    {
      "Description": null,
      "ExpectedResult": null,
      "OrderNumber": 0,
      "Result": "NotRun",
      "Id": "b85cea17-60ce-48ba-923f-f7c332c99cda"
    }
  ],
  "Self": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    }
  ]
}

Status Code

200 - OK

PUT


Updates an agile run.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if request is completed successfully.

Example - PUT

Example of updating an agile run via PUT.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of Agile Run to update

Request Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Steps": [
    {
      "Description": "Click date field",
      "ExpectedResult": "Date field get's focus",
      "OrderNumber": 0,
      "Result": "Passed"
    },
    {
      "Description": "Enter date 2010-1-1",
      "ExpectedResult": "Date is accepted",
      "OrderNumber": 1,
      "Result": "Passed"
    },
    {
      "Description": "Click save",
      "ExpectedResult": "User is prompted with warning about paste due date",
      "OrderNumber": 2,
      "ActualResult": "No prompt displayed",
      "Result": "Failed"
    }
  ],
  "Name": "Creating invoice with paste due date value"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Description": "Creating invoices for past dates is allowed, but we want a warning to be displayed to the user.",
  "Name": "Creating invoice with paste due date value",
  "Notes": null,
  "Number": 1,
  "Objective": null,
  "PostCondition": null,
  "PreCondition": null,
  "PriorityId": "a79e5778-befc-4ffe-b910-873ff737296c",
  "StatusId": "f304c468-58d4-4245-a9c8-7b61a42f57f3",
  "TypeId": "27537607-6c59-4d7c-b812-d5dff13ff738",
  "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25",
  "OrderNumber": 0,
  "ProjectId": "ef7b7b88-b990-4cb9-98b5-2d89786e51f3",
  "ProjectName": "Test Project",
  "PackageName": "Execution Sets",
  "EstimatedDuration": null,
  "ActualDuration": null,
  "ExecutionStatus": "Failed",
  "AgileRunNumberReadOnly": false,
  "Expands": [
    "Widgets",
    "FieldValues",
    "Project"
  ],
  "Steps": [
    {
      "Description": "Click date field",
      "ExpectedResult": "Date field get's focus",
      "OrderNumber": 0,
      "Result": "Passed",
      "Id": "945c7670-dd34-4d1a-b4d6-267f7959c3be"
    },
    {
      "Description": "Enter date 2010-1-1",
      "ExpectedResult": "Date is accepted",
      "OrderNumber": 1,
      "Result": "Passed",
      "Id": "2e020ac3-8013-4daf-b5a4-b9ca9323da8e"
    },
    {
      "Description": "Click save",
      "ExpectedResult": "User is prompted with warning about paste due date",
      "OrderNumber": 2,
      "ActualResult": "No prompt displayed",
      "Result": "Failed",
      "Id": "db2799e8-966d-4548-bb04-af678ba75339"
    }
  ],
  "Self": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    }
  ]
}

Status Code

200 - OK

Resource: Agile Run All Relationships ( /api/agilerun/{id}/allrelationships )

A resource representing the set of relationships belonging to the Agile Run (includes the full graph of related entities, not just those which can be reached through destination and source->destination directed relationships).

This resource supports the following methods: GET

Methods

GET


Retrieves all relationships

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the relationships associated with this entity.
404 - NotFoundReturned if the entity does not exist.

Example - Retrieve Relationships

Retrieve relationships (the response is a generic example, and does not necessarily represent the type of relationships that would be returned for this Entity Type).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}5E2814AF-1800-4C8F-B7C8-2ED9FADF98D0The ID of the entity to retrieve the relationships for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "EntityId": "8F00D2CE-6243-4956-AF89-60B7B9755A9B",
  "Number": "1",
  "Name": "Some Script",
  "EntityType": "TestScript",
  "AssignedTo": "joeb",
  "Status": "Draft",
  "Priority": "High",
  "Type": "Functional",
  "PackageId": "c232382b-0c66-475b-b59b-8753d4c5377b",
  "PackageName": "Cycle 1",
  "PackageEntityType": "ScriptPackage",
  "PackagePath": "/Script Library/Cycle 1",
  "RelationshipId": null,
  "RelationshipTypeKey": "ScriptToRequirementCoverage",
  "RelationshipType": "Coverage",
  "Relation": "Covered By",
  "RelationshipDirection": "Source -> Destination",
  "CanDelete": true,
  "CanEdit": false,
  "Children": [
    {
      "EntityId": "4155F037-B778-4E9D-B942-0CC237D51038",
      "Number": "2",
      "Name": "Some Requirement",
      "EntityType": "Requirement",
      "AssignedTo": "janed",
      "Status": "Draft",
      "Priority": "Medium",
      "Type": "Functional",
      "PackageId": "454bc5ca-3496-4abb-a69a-919bf5f3ca0b",
      "PackageName": "Cycle 1",
      "PackageEntityType": "RequirementPackage",
      "PackagePath": "/Requirements/Cycle 1",
      "RelationshipId": null,
      "RelationshipTypeKey": "ScriptToRequirementCoverage",
      "RelationshipType": "Coverage",
      "Relation": "Covered By",
      "RelationshipDirection": "Destination -> Source",
      "CanDelete": false,
      "CanEdit": true,
      "Children": [],
      "Links": [
        {
          "Href": "http://localhost/api",
          "Rel": "Entity"
        }
      ]
    }
  ],
  "Links": [
    {
      "Href": "http://localhost/api",
      "Rel": "Entity"
    }
  ]
}

Status Code

200 - OK

Resource: Agile Run Relationships ( /api/agilerun/{id}/relationships )

A resource representing the set of relationships belonging to the Agile Run.

This resource supports the following methods: GET

Methods

GET


Retrieves all relationships

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the relationships associated with this entity.
404 - NotFoundReturned if the entity does not exist.

Example - Retrieve Relationships

Retrieve relationships (the response is a generic example, and does not necessarily represent the type of relationships that would be returned for this Entity Type).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}5E2814AF-1800-4C8F-B7C8-2ED9FADF98D0The ID of the entity to retrieve the relationships for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "EntityId": "8F00D2CE-6243-4956-AF89-60B7B9755A9B",
  "Number": "1",
  "Name": "Some Script",
  "EntityType": "TestScript",
  "AssignedTo": "joeb",
  "Status": "Draft",
  "Priority": "High",
  "Type": "Functional",
  "PackageId": "c232382b-0c66-475b-b59b-8753d4c5377b",
  "PackageName": "Cycle 1",
  "PackageEntityType": "ScriptPackage",
  "PackagePath": "/Script Library/Cycle 1",
  "RelationshipId": null,
  "RelationshipTypeKey": "ScriptToRequirementCoverage",
  "RelationshipType": "Coverage",
  "Relation": "Covered By",
  "RelationshipDirection": "Source -> Destination",
  "CanDelete": true,
  "CanEdit": false,
  "Children": [
    {
      "EntityId": "4155F037-B778-4E9D-B942-0CC237D51038",
      "Number": "2",
      "Name": "Some Requirement",
      "EntityType": "Requirement",
      "AssignedTo": "janed",
      "Status": "Draft",
      "Priority": "Medium",
      "Type": "Functional",
      "PackageId": "454bc5ca-3496-4abb-a69a-919bf5f3ca0b",
      "PackageName": "Cycle 1",
      "PackageEntityType": "RequirementPackage",
      "PackagePath": "/Requirements/Cycle 1",
      "RelationshipId": null,
      "RelationshipTypeKey": "ScriptToRequirementCoverage",
      "RelationshipType": "Coverage",
      "Relation": "Covered By",
      "RelationshipDirection": "Destination -> Source",
      "CanDelete": false,
      "CanEdit": true,
      "Children": [],
      "Links": [
        {
          "Href": "http://localhost/api",
          "Rel": "Entity"
        }
      ]
    }
  ],
  "Links": [
    {
      "Href": "http://localhost/api",
      "Rel": "Entity"
    }
  ]
}

Status Code

200 - OK

Resource: Agile Run Step Attachments ( /api/agilerun/{runId}/step/{stepId}/attachments )

Agile Run Step Attachments (collection) resource for fetching attachments associated with an agile run step, or adding new attachments to the agile run step.

This resource supports the following methods: GET, POST

Methods

GET


Retrieves list of attachments for the agile run step.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you have insufficient permissions to list attachments for this agile run step.
404 - NotFoundReturned if run or step does not exist.

Example - GET

Retrieves a list of all attachments associated with a step result.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}b716ac5e-61a3-4394-9b50-a13014129864The unique identifier (GUID) of the agile run.
{stepId}cbd88178-5e33-43b4-8172-01beaf5bdb75The unique identifier (GUID) of the agile run step.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "RunId": "b716ac5e-61a3-4394-9b50-a13014129864",
      "Id": "9b02c840-c330-4725-b743-b40181420bc2",
      "StepId": "cbd88178-5e33-43b4-8172-01beaf5bdb75",
      "Name": "screenshot 1",
      "FileName": "screenshot1.png",
      "ContentType": "image/png",
      "CreatedAt": "2012-01-01T14:04:05Z",
      "CreatedById": "2b364daa-0dff-4a6f-8554-f5963d3011be",
      "Size": 122454,
      "Self": "http://localhost/api/stepresult/b716ac5e-61a3-4394-9b50-a13014129864/step/cbd88178-5e33-43b4-8172-01beaf5bdb75/attachment/9b02c840-c330-4725-b743-b40181420bc2",
      "Content": "http://localhost/api/attachment/9b02c840-c330-4725-b743-b40181420bc2/contents"
    },
    {
      "RunId": "b716ac5e-61a3-4394-9b50-a13014129864",
      "Id": "5669f517-5ef4-40b6-856f-dbd488319da6",
      "StepId": "cbd88178-5e33-43b4-8172-01beaf5bdb75",
      "Name": "notes.txt",
      "FileName": "notes",
      "ContentType": "text/plain",
      "CreatedAt": "2012-01-01T14:04:05Z",
      "CreatedById": "2b364daa-0dff-4a6f-8554-f5963d3011be",
      "Size": 3,
      "Self": "http://localhost/api/stepresult/b716ac5e-61a3-4394-9b50-a13014129864/step/cbd88178-5e33-43b4-8172-01beaf5bdb75/attachment/5669f517-5ef4-40b6-856f-dbd488319da6",
      "Content": "http://localhost/api/attachment/5669f517-5ef4-40b6-856f-dbd488319da6/contents"
    }
  ]
}

Status Code

200 - OK

POST


Upload one or more attachments for this agile run step.

Required Permissions

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
201 - CreatedReturned if the attachments were uploaded successfully.
403 - ForbiddenReturned if the multipart request did not contain any files.
415 - UnsupportedMediaTypeReturned if the request is not mime multipart.

Example - POST

Uploads one or more files using a mime multipart request (this example shows a response where two files were uploaded).

Request Headers

KeyValueDescription
Content-Typemultipart/mixed; boundary=65bf6b94-c91c-442c-abe7-f41444d7c71f

Request Parameters

KeyValueDescription
{runId}b716ac5e-61a3-4394-9b50-a13014129864The unique identifier (GUID) of the agile run.
{stepId}cbd88178-5e33-43b4-8172-01beaf5bdb75The unique identifier (GUID) of the agile run step.

Request Body

--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename=screenshot1.png; name="screenshot 1"; size=122454
Content-Type: image/png
Content-Length: 3
...
--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename=notes.txt; name=notes; size=3
Content-Type: text/plain
Content-Length: 3
ABC
--65bf6b94-c91c-442c-abe7-f41444d7c71f--

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "RunId": "b716ac5e-61a3-4394-9b50-a13014129864",
      "Id": "9b02c840-c330-4725-b743-b40181420bc2",
      "StepId": "cbd88178-5e33-43b4-8172-01beaf5bdb75",
      "Name": "screenshot 1",
      "FileName": "screenshot1.png",
      "ContentType": "image/png",
      "CreatedAt": "2012-01-01T14:04:05Z",
      "CreatedById": "2b364daa-0dff-4a6f-8554-f5963d3011be",
      "Size": 122454,
      "Self": "http://localhost/api/stepresult/b716ac5e-61a3-4394-9b50-a13014129864/step/cbd88178-5e33-43b4-8172-01beaf5bdb75/attachment/9b02c840-c330-4725-b743-b40181420bc2",
      "Content": "http://localhost/api/attachment/9b02c840-c330-4725-b743-b40181420bc2/contents"
    },
    {
      "RunId": "b716ac5e-61a3-4394-9b50-a13014129864",
      "Id": "5669f517-5ef4-40b6-856f-dbd488319da6",
      "StepId": "cbd88178-5e33-43b4-8172-01beaf5bdb75",
      "Name": "notes.txt",
      "FileName": "notes",
      "ContentType": "text/plain",
      "CreatedAt": "2012-01-01T14:04:05Z",
      "CreatedById": "2b364daa-0dff-4a6f-8554-f5963d3011be",
      "Size": 3,
      "Self": "http://localhost/api/stepresult/b716ac5e-61a3-4394-9b50-a13014129864/step/cbd88178-5e33-43b4-8172-01beaf5bdb75/attachment/5669f517-5ef4-40b6-856f-dbd488319da6",
      "Content": "http://localhost/api/attachment/5669f517-5ef4-40b6-856f-dbd488319da6/contents"
    }
  ]
}

Status Code

201 - Created

Resource: Agile Run Step Incident ( /api/agilerun/{runId}/step/{stepId}/incident/{incidentId} )

Allows you to manage a single incident linked to a agile run step.

This resource supports the following methods: DELETE, GET

Methods

DELETE


Removes an incident link belonging to a agile run step.

Required Permissions

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
200 - OKReturned if link was removed successfully.
403 - ForbiddenReturned if incident link can not be removed (normally because you don't have necessary permissions).
404 - NotFoundReturned if agile run, step or incident do not exist.

Example - Remove incident link

Remove link between agile run step and incident.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}b716ac5e-61a3-4394-9b50-a13014129864The unique identifier (GUID) of the agile run.
{stepId}cbd88178-5e33-43b4-8172-01beaf5bdb75The unique identifier (GUID) of the agile run step.
{incidentId}15759d66-ae69-476e-be2a-d1a5eb59ab5eThe unique identifier (GUID) of the incident.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves an an incident link belonging to a agile run step.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the link.
404 - NotFoundReturned if agile run, step or incident do not exist.

Example - Get incident link

Retrieves a single agile run step to incident link.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}b716ac5e-61a3-4394-9b50-a13014129864The unique identifier (GUID) of the agile run.
{stepId}cbd88178-5e33-43b4-8172-01beaf5bdb75The unique identifier (GUID) of the agile run step.
{incidentId}15759d66-ae69-476e-be2a-d1a5eb59ab5eThe unique identifier (GUID) of the incident.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "StepId": "cbd88178-5e33-43b4-8172-01beaf5bdb75",
  "RunId": "b716ac5e-61a3-4394-9b50-a13014129864",
  "IncidentId": "15759d66-ae69-476e-be2a-d1a5eb59ab5e",
  "Expands": [
    "Incident",
    "Run"
  ],
  "Self": "http://localhost/api/agilerun/b716ac5e-61a3-4394-9b50-a13014129864/step/cbd88178-5e33-43b4-8172-01beaf5bdb75/incident/15759d66-ae69-476e-be2a-d1a5eb59ab5e",
  "Links": [
    {
      "Href": "http://localhost/api/incident/15759d66-ae69-476e-be2a-d1a5eb59ab5e",
      "Rel": "Incident"
    }
  ]
}

Status Code

200 - OK

Resource: Agile Run Step Incidents ( /api/agilerun/{runId}/step/{stepId}/incidents )

Agile Run Step Incidents (collection) resource - used to retrieve a collection of all incidents linked to an agile run step, or to link a new incident to a step.

This resource supports the following methods: GET, POST

Methods

GET


Retrieves list of incidents linked to the agile run step.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the list of incidents associated with this agile run step.
404 - NotFoundReturned if agile run, step or incident does not exist.

Example - Get all incident links associated with a agile run step

Retrieves all incidents linked to a agile run step.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}b716ac5e-61a3-4394-9b50-a13014129864The unique identifier (GUID) of the agile run.
{stepId}cbd88178-5e33-43b4-8172-01beaf5bdb75The unique identifier (GUID) of the agile run step.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "StepId": "cbd88178-5e33-43b4-8172-01beaf5bdb75",
      "RunId": "b716ac5e-61a3-4394-9b50-a13014129864",
      "IncidentId": "0f61b42d-87f9-40b8-89ee-1bc12a6b5dba",
      "Expands": [
        "Incident",
        "Run"
      ],
      "Self": "http://localhost/api/agilerun/b716ac5e-61a3-4394-9b50-a13014129864/step/cbd88178-5e33-43b4-8172-01beaf5bdb75/incident/0f61b42d-87f9-40b8-89ee-1bc12a6b5dba",
      "Links": [
        {
          "Href": "http://localhost/api/incident/0f61b42d-87f9-40b8-89ee-1bc12a6b5dba",
          "Rel": "Incident"
        }
      ]
    },
    {
      "StepId": "cbd88178-5e33-43b4-8172-01beaf5bdb75",
      "RunId": "b716ac5e-61a3-4394-9b50-a13014129864",
      "IncidentId": "24dfb384-2026-487d-b04b-2de429933508",
      "Expands": [
        "Incident",
        "Run"
      ],
      "Self": "http://localhost/api/agilerun/b716ac5e-61a3-4394-9b50-a13014129864/step/cbd88178-5e33-43b4-8172-01beaf5bdb75/incident/24dfb384-2026-487d-b04b-2de429933508",
      "Links": [
        {
          "Href": "http://localhost/api/incident/24dfb384-2026-487d-b04b-2de429933508",
          "Rel": "Incident"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Create agile run step incident link.

Required Permissions

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
200 - OKReturned if the incident was already linked to this step.
201 - CreatedReturned if link to incident was created successfully.
403 - ForbiddenReturned if insufficient permission to link to this incident.
404 - NotFoundReturned if agile run, step or incident does not exist.

Example - Create a new link

Create a new incident to agile run step link.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}b716ac5e-61a3-4394-9b50-a13014129864The unique identifier (GUID) of the agile run.
{stepId}cbd88178-5e33-43b4-8172-01beaf5bdb75The unique identifier (GUID) of the agile run step.

Request Body

{
  "StepResultId": null,
  "IncidentId": "0f61b42d-87f9-40b8-89ee-1bc12a6b5dba"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/stepresult/B849F98E-62B2-460C-97EF-49E6C478A3F9/incident/0F61B42D-87F9-40B8-89EE-1BC12A6B5DBA

Response Body

{
  "StepId": "cbd88178-5e33-43b4-8172-01beaf5bdb75",
  "RunId": "b716ac5e-61a3-4394-9b50-a13014129864",
  "IncidentId": "0f61b42d-87f9-40b8-89ee-1bc12a6b5dba",
  "Expands": [
    "Incident",
    "Run"
  ],
  "Self": "http://localhost/api/agilerun/b716ac5e-61a3-4394-9b50-a13014129864/step/cbd88178-5e33-43b4-8172-01beaf5bdb75/incident/0f61b42d-87f9-40b8-89ee-1bc12a6b5dba",
  "Links": [
    {
      "Href": "http://localhost/api/incident/0f61b42d-87f9-40b8-89ee-1bc12a6b5dba",
      "Rel": "Incident"
    }
  ]
}

Status Code

201 - Created

Resource: Agile Run Step Result Attachment ( /api/agilerun/{runId}/step/{stepId}/attachment/{attachmentId} )

Allows you to manage a single step attachment.

This resource supports the following methods: DELETE

Methods

DELETE


Deletes an attachment from the agile run step.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you have insufficient permissions to delete the attachment.
404 - NotFoundReturned if the attachment or agile run step does not exist.

Example - Delete attachment

Delete an attachment associated with an agile run step.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}2175D908-5EF1-4CF0-875C-CED70B2537B0The unique identifier (GUID) of the agile run.
{stepId}4A685B80-BC5A-42BE-82E0-616D0E70FF05The unique identifier (GUID) of the step the attachment belongs to in the agile run.
{attachmentId}B1105C56-43AB-4F66-AFDE-1135AAC851E5The unique identifier (GUID) of the attachment to delete

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

Resource: Agile Runs ( /api/agileruns )

Agile Runs collection resource

Root Relation: AgileRuns

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of agile runs that are visible to the user.

This method supports the TQL query parameters tql, $top, $take and $inlinecount. See TQL Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if request is completed successfully.

Example - GET (filtered by TQL Query)

Retrieves agile runs matching a TQL query.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
tqlName ~ 'Report'The TQL query to execute.
$top5Maximum number of results to return (defaults to 25).
$skip0Number of results to skip before return the $top number of results matching the query.
$expandsStepsThe aditional fields to expand

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 1,
  "Items": [
    {
      "Id": "e7a8ade8-2452-4856-9f7d-6296b3b82fc8",
      "Description": null,
      "Name": "Report pagination",
      "Notes": null,
      "Number": 1,
      "Objective": null,
      "PostCondition": null,
      "PreCondition": null,
      "PriorityId": "a79e5778-befc-4ffe-b910-873ff737296c",
      "StatusId": "f304c468-58d4-4245-a9c8-7b61a42f57f3",
      "TypeId": "27537607-6c59-4d7c-b812-d5dff13ff738",
      "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25",
      "OrderNumber": 1,
      "ProjectId": "ef7b7b88-b990-4cb9-98b5-2d89786e51f3",
      "ProjectName": "Test Project",
      "PackageName": "Execution Sets",
      "EstimatedDuration": null,
      "ActualDuration": null,
      "ExecutionStatus": "Not Run",
      "AgileRunNumberReadOnly": false,
      "Expands": [
        "Widgets",
        "FieldValues"
      ],
      "Steps": [
        {
          "Description": "View report with more then 25 rows of data",
          "ExpectedResult": "Next page button is displayed",
          "Notes": "Use HTML report mode",
          "OrderNumber": 0,
          "Result": "NotRun",
          "Id": "23d16899-703f-4e4a-84af-6b87e3bd3adb"
        },
        {
          "Description": "Click next page button",
          "ExpectedResult": "Page 2 is displayed",
          "Notes": "Use HTML report mode",
          "OrderNumber": 1,
          "Result": "NotRun",
          "Id": "ca5a155d-7c4b-4876-bebe-c6bf8649465d"
        },
        {
          "Description": "Click last page button",
          "ExpectedResult": "Final page of results is displayed, next page button is disabled.",
          "Notes": "Use HTML report mode",
          "Data": "Use the large sample data set",
          "OrderNumber": 2,
          "Result": "NotRun",
          "Id": "b37d130a-98b9-4b2a-9b79-af9fcfae6177"
        }
      ],
      "Self": "http://localhost/api/agilerun/e7a8ade8-2452-4856-9f7d-6296b3b82fc8",
      "Links": [
        {
          "Href": "http://localhost/api/agilerun/e7a8ade8-2452-4856-9f7d-6296b3b82fc8/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/agilerun/e7a8ade8-2452-4856-9f7d-6296b3b82fc8/allrelationships",
          "Rel": "AllRelationships"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Example - GET (no filter)

Retrieves agile runs matching a TQL query.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$top5Maximum number of results to return (defaults to 25).
$skip0Number of results to skip before return the $top number of results matching the query.
$expandsStepsThe aditional fields to expand

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 2,
  "Items": [
    {
      "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Description": null,
      "Name": "Agile Run Started At 2-05-2012 10:00:08 p.m.",
      "Notes": null,
      "Number": 1,
      "Objective": null,
      "PostCondition": null,
      "PreCondition": null,
      "PriorityId": "a79e5778-befc-4ffe-b910-873ff737296c",
      "StatusId": "f304c468-58d4-4245-a9c8-7b61a42f57f3",
      "TypeId": "27537607-6c59-4d7c-b812-d5dff13ff738",
      "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25",
      "OrderNumber": 0,
      "ProjectId": "ef7b7b88-b990-4cb9-98b5-2d89786e51f3",
      "ProjectName": "Test Project",
      "PackageName": "Execution Sets",
      "EstimatedDuration": null,
      "ActualDuration": null,
      "ExecutionStatus": "Not Run",
      "AgileRunNumberReadOnly": false,
      "Expands": [
        "Widgets",
        "FieldValues"
      ],
      "Steps": [
        {
          "Description": null,
          "ExpectedResult": null,
          "OrderNumber": 0,
          "Result": "NotRun",
          "Id": "b85cea17-60ce-48ba-923f-f7c332c99cda"
        }
      ],
      "Self": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Links": [
        {
          "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
          "Rel": "AllRelationships"
        }
      ]
    },
    {
      "Id": "e7a8ade8-2452-4856-9f7d-6296b3b82fc8",
      "Description": null,
      "Name": "Report pagination",
      "Notes": null,
      "Number": 1,
      "Objective": null,
      "PostCondition": null,
      "PreCondition": null,
      "PriorityId": "a79e5778-befc-4ffe-b910-873ff737296c",
      "StatusId": "f304c468-58d4-4245-a9c8-7b61a42f57f3",
      "TypeId": "27537607-6c59-4d7c-b812-d5dff13ff738",
      "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25",
      "OrderNumber": 1,
      "ProjectId": "ef7b7b88-b990-4cb9-98b5-2d89786e51f3",
      "ProjectName": "Test Project",
      "PackageName": "Execution Sets",
      "EstimatedDuration": null,
      "ActualDuration": null,
      "ExecutionStatus": "Not Run",
      "AgileRunNumberReadOnly": false,
      "Expands": [
        "Widgets",
        "FieldValues"
      ],
      "Steps": [
        {
          "Description": "View report with more then 25 rows of data",
          "ExpectedResult": "Next page button is displayed",
          "Notes": "Use HTML report mode",
          "OrderNumber": 0,
          "Result": "NotRun",
          "Id": "23d16899-703f-4e4a-84af-6b87e3bd3adb"
        },
        {
          "Description": "Click next page button",
          "ExpectedResult": "Page 2 is displayed",
          "Notes": "Use HTML report mode",
          "OrderNumber": 1,
          "Result": "NotRun",
          "Id": "ca5a155d-7c4b-4876-bebe-c6bf8649465d"
        },
        {
          "Description": "Click last page button",
          "ExpectedResult": "Final page of results is displayed, next page button is disabled.",
          "Notes": "Use HTML report mode",
          "Data": "Use the large sample data set",
          "OrderNumber": 2,
          "Result": "NotRun",
          "Id": "b37d130a-98b9-4b2a-9b79-af9fcfae6177"
        }
      ],
      "Self": "http://localhost/api/agilerun/e7a8ade8-2452-4856-9f7d-6296b3b82fc8",
      "Links": [
        {
          "Href": "http://localhost/api/agilerun/e7a8ade8-2452-4856-9f7d-6296b3b82fc8/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/agilerun/e7a8ade8-2452-4856-9f7d-6296b3b82fc8/allrelationships",
          "Rel": "AllRelationships"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Creates a new agile run.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if agile run is created successfully.

Example - Create agile run (minimum required information)

Example of creating a new agile run with the bare minimum of information (supplying only the package where the agile run should be created).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Body

{ "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25" }

Response Headers

KeyValueDescription
Locationhttp://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Description": null,
  "Name": "Agile Run Started At 2-05-2012 10:00:08 p.m.",
  "Notes": null,
  "Number": 1,
  "Objective": null,
  "PostCondition": null,
  "PreCondition": null,
  "PriorityId": "a79e5778-befc-4ffe-b910-873ff737296c",
  "StatusId": "f304c468-58d4-4245-a9c8-7b61a42f57f3",
  "TypeId": "27537607-6c59-4d7c-b812-d5dff13ff738",
  "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25",
  "OrderNumber": 0,
  "ProjectId": "ef7b7b88-b990-4cb9-98b5-2d89786e51f3",
  "ProjectName": "Test Project",
  "PackageName": "Execution Sets",
  "EstimatedDuration": null,
  "ActualDuration": null,
  "ExecutionStatus": "Not Run",
  "AgileRunNumberReadOnly": false,
  "Expands": [
    "Widgets",
    "FieldValues",
    "Steps"
  ],
  "Self": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    }
  ]
}

Status Code

201 - Created

Example - Create agile run (all fields populated)

Example of creating a new agile run with all inbuilt fields populated.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Body

{
  "AssignedToId": "f508eb90-445e-41ba-9921-b1740ae930f8",
  "Description": "Attempting to login with an invalid password should not allow access to the application",
  "Steps": [
    {
      "Description": "Enter login and press tab",
      "ExpectedResult": "Focus moves to password field",
      "OrderNumber": 0,
      "Result": "Passed"
    },
    {
      "Description": "Enter invalid password and press enter",
      "ExpectedResult": "Error message displayed stating that username or password is invalid.",
      "Notes": "Invalid passwords must be longer then minimum length for a valid password e.g. 6 characters",
      "Data": "Example passwords: 'invalid', 'unkonwn', '$$$$$'",
      "OrderNumber": 1,
      "ActualResult": "Was logged in successfully",
      "Result": "Failed"
    }
  ],
  "Name": "Login using invalid password",
  "Notes": "Some notes about the script",
  "Number": 123,
  "Objective": "To determine if app password validation is working correctly",
  "PostCondition": "Access must be denied",
  "PreCondition": "User must exist, but with a different password to what we will attempt to login with",
  "PriorityId": "a79e5778-befc-4ffe-b910-873ff737296c",
  "StatusId": "f304c468-58d4-4245-a9c8-7b61a42f57f3",
  "TypeId": "27537607-6c59-4d7c-b812-d5dff13ff738",
  "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25",
  "OrderNumber": 0,
  "EstimatedDuration": "5m",
  "ActualDuration": "5m"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "AssignedToId": "f508eb90-445e-41ba-9921-b1740ae930f8",
  "AssignedTo": "Joe Bloggs",
  "Description": "Attempting to login with an invalid password should not allow access to the application",
  "Name": "Login using invalid password",
  "Notes": null,
  "Number": 123,
  "Objective": null,
  "PostCondition": null,
  "PreCondition": null,
  "PriorityId": "a79e5778-befc-4ffe-b910-873ff737296c",
  "StatusId": "f304c468-58d4-4245-a9c8-7b61a42f57f3",
  "TypeId": "27537607-6c59-4d7c-b812-d5dff13ff738",
  "PackageId": "a5c52dc7-e849-4af9-ab99-a01401130d25",
  "OrderNumber": 0,
  "ProjectId": "ef7b7b88-b990-4cb9-98b5-2d89786e51f3",
  "ProjectName": "Test Project",
  "PackageName": "Execution Sets",
  "EstimatedDuration": null,
  "ActualDuration": null,
  "ExecutionStatus": "Failed",
  "AgileRunNumberReadOnly": false,
  "Expands": [
    "Widgets",
    "FieldValues"
  ],
  "Steps": [
    {
      "Description": "Enter login and press tab",
      "ExpectedResult": "Focus moves to password field",
      "OrderNumber": 0,
      "Result": "Passed",
      "Id": "7c1d0d2d-aa32-4655-b08a-b95367a1b631"
    },
    {
      "Description": "Enter invalid password and press enter",
      "ExpectedResult": "Error message displayed stating that username or password is invalid.",
      "Notes": "Invalid passwords must be longer then minimum length for a valid password e.g. 6 characters",
      "Data": "Example passwords: 'invalid', 'unkonwn', '$$$$$'",
      "OrderNumber": 1,
      "ActualResult": "Was logged in successfully",
      "Result": "Failed",
      "Id": "ea8bc4de-cfaf-4db8-811b-f88449e1e675"
    }
  ],
  "Self": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/agilerun/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    }
  ]
}

Status Code

201 - Created

Resource: Assigned To Search ( /api/assignedtosearch )

Allows the searching of applicable assigned to values by partial name (including groups, users and special values such as 'Me').

Root Relation: AssignedToSearch

This resource supports the following methods: GET, POST

Methods

GET


Searches for users, groups and special users e.g. currently logged in user (self) by partial name match

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
200 - OKReturned if the query request was satisfied.

Example - Search using query

Search for all 'Assigned To' values starting with the letter M

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
queryMThe partial values query

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 3,
  "Total": 25,
  "Items": [
    {
      "Id": "357ec7c6-f1e1-4b4b-b248-c7346774d466",
      "Type": "Group",
      "Name": "Managers",
      "GlobalId": "Group:357ec7c6-f1e1-4b4b-b248-c7346774d466",
      "CssClass": "assigned-to-group"
    },
    {
      "Type": "Self",
      "Name": "Me",
      "GlobalId": "Self",
      "CssClass": "assigned-to-self"
    },
    {
      "Id": "e68c26d3-888f-4fa5-96e3-88c5d6368fb9",
      "Type": "User",
      "Name": "Michael Mango",
      "GlobalId": "User:e68c26d3-888f-4fa5-96e3-88c5d6368fb9",
      "CssClass": "assigned-to-user"
    }
  ],
  "Self": "http://localhost/api/api/assignedtosearch?query=M",
  "Links": [
    {
      "Href": "http://localhost/api/api/assignedtosearch?query=M&$skip=3&$top=3",
      "Rel": "next"
    },
    {
      "Href": "http://localhost/api/api/assignedtosearch?query=M&$skip=22&$top=3",
      "Rel": "last"
    }
  ]
}

Status Code

200 - OK

POST


Searches for users, groups and special users e.g. currently logged in user (self) by partial name match (using POST to allow large existing value queries)

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
200 - OKReturned if the query request was satisfied.

Example - Search using query

Search for all 'Assigned To' values starting with the letter M

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
queryMThe partial values query

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 3,
  "Total": 25,
  "Items": [
    {
      "Id": "357ec7c6-f1e1-4b4b-b248-c7346774d466",
      "Type": "Group",
      "Name": "Managers",
      "GlobalId": "Group:357ec7c6-f1e1-4b4b-b248-c7346774d466",
      "CssClass": "assigned-to-group"
    },
    {
      "Type": "Self",
      "Name": "Me",
      "GlobalId": "Self",
      "CssClass": "assigned-to-self"
    },
    {
      "Id": "e68c26d3-888f-4fa5-96e3-88c5d6368fb9",
      "Type": "User",
      "Name": "Michael Mango",
      "GlobalId": "User:e68c26d3-888f-4fa5-96e3-88c5d6368fb9",
      "CssClass": "assigned-to-user"
    }
  ],
  "Self": "http://localhost/api/api/assignedtosearch",
  "Links": [
    {
      "Href": "http://localhost/api/api/assignedtosearch?$skip=3&$top=3",
      "Rel": "next"
    },
    {
      "Href": "http://localhost/api/api/assignedtosearch?$skip=22&$top=3",
      "Rel": "last"
    }
  ]
}

Status Code

200 - OK

Resource: Attachment Contents ( /api/attachment/{id}/contents )

Used to retrieve the contents of an attachment.

This resource supports the following methods: GET

Methods

GET


Retrieves the contents of an attachment.

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
200 - OKReturned if the request is completed successfully.
404 - NotFoundReturned if the attachment does not exist.

Example - Retrieve Attachment Contents

Example of retrieving the contents of an attachment.

Request Headers

KeyValueDescription
Accept*/*

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of the attachment to retrieve contents for.

Response Headers

KeyValueDescription
Content-Typeapplication/octet-stream

Status Code

200 - OK

Resource: Automated Test ( /api/automatedtest/{id} )

Automated test resource

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Deletes the automated test by its unique identifier

Required Permissions

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
200 - OKReturned if the automated test was deleted successfully.
403 - ForbiddenReturned if the automated test can not be deleted (normally if the necessary permissions to complete the request have not been met, or the automated test has associated assignments).
404 - NotFoundReturned if the automated test package was not found.

Example - Delete automated test

Delete automated test by its unique identifier.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}7FABE725-28A0-4C48-A6AF-AAF4041223D2The Unique identifier of automated test to delete.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves an automated test by its unique identifier.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request is completed successfully.
403 - ForbiddenReturned if the required permissions to view the automated test have not been met.
404 - NotFoundReturned if the automated test does not exist.

Example - Get automated test

Retrieve automated test by its unique identifier.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}DFF56A5F-40FA-41D5-8BC8-33C3D0014368Unique identifier of the automated test to return.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "dff56a5f-40fa-41d5-8bc8-33c3d0014368",
  "Type": "UnitTest",
  "Name": "JUnit Results",
  "CreatedAt": "2012-01-02T15:05:06Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "CreatedBy": "joeb",
  "LastUpdatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "LastUpdatedBy": "joeb",
  "AssignedToId": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "AssignedTo": "joeb",
  "PackageId": "68f38eb7-9882-41b8-9749-712c43dc3f51",
  "ProjectId": "4f0d1bc3-3247-4ad0-b753-aaa538d8c523",
  "ProjectName": "Test Project",
  "PackageName": "Script Library",
  "OrderNumber": 1,
  "Expands": [
    "Assignments",
    "Configuration"
  ],
  "Self": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/assignments",
      "Rel": "Assignments"
    }
  ]
}

Status Code

200 - OK

PUT


Creates a new automated test.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the request is completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the automated test does not exist.

Example - Update Automated Test

Update automated test.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}DFF56A5F-40FA-41D5-8BC8-33C3D0014368Unique identifier of the automated test to return.

Request Body

{
  "Id": "dff56a5f-40fa-41d5-8bc8-33c3d0014368",
  "Type": "UnitTest",
  "Name": "Cycle 2 JUnit Results",
  "AssignedToId": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "PackageId": "68f38eb7-9882-41b8-9749-712c43dc3f51",
  "OrderNumber": 1,
  "Configuration": {
    "Type": "JUnit"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "dff56a5f-40fa-41d5-8bc8-33c3d0014368",
  "Type": "UnitTest",
  "Name": "Cycle 2 JUnit Results",
  "CreatedAt": "2012-01-02T15:05:06Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "CreatedBy": "joeb",
  "LastUpdatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "LastUpdatedBy": "joeb",
  "AssignedToId": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "AssignedTo": "joeb",
  "PackageId": "68f38eb7-9882-41b8-9749-712c43dc3f51",
  "ProjectId": "4f0d1bc3-3247-4ad0-b753-aaa538d8c523",
  "ProjectName": "Test Project",
  "PackageName": "Script Library",
  "OrderNumber": 1,
  "Expands": [
    "Assignments",
    "Configuration"
  ],
  "Self": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/assignments",
      "Rel": "Assignments"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test All Relationships ( /api/automatedtest/{id}/allrelationships )

A resource representing the set of relationships belonging to the Automated Test (includes the full graph of related entities, not just those which can be reached through destination and source->destination directed relationships).

This resource supports the following methods: GET

Methods

GET


Retrieves all relationships

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the relationships associated with this entity.
404 - NotFoundReturned if the entity does not exist.

Example - Retrieve Relationships

Retrieve relationships (the response is a generic example, and does not necessarily represent the type of relationships that would be returned for this Entity Type).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}5E2814AF-1800-4C8F-B7C8-2ED9FADF98D0The ID of the entity to retrieve the relationships for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "EntityId": "8F00D2CE-6243-4956-AF89-60B7B9755A9B",
  "Number": "1",
  "Name": "Some Script",
  "EntityType": "TestScript",
  "AssignedTo": "joeb",
  "Status": "Draft",
  "Priority": "High",
  "Type": "Functional",
  "PackageId": "c232382b-0c66-475b-b59b-8753d4c5377b",
  "PackageName": "Cycle 1",
  "PackageEntityType": "ScriptPackage",
  "PackagePath": "/Script Library/Cycle 1",
  "RelationshipId": null,
  "RelationshipTypeKey": "ScriptToRequirementCoverage",
  "RelationshipType": "Coverage",
  "Relation": "Covered By",
  "RelationshipDirection": "Source -> Destination",
  "CanDelete": true,
  "CanEdit": false,
  "Children": [
    {
      "EntityId": "4155F037-B778-4E9D-B942-0CC237D51038",
      "Number": "2",
      "Name": "Some Requirement",
      "EntityType": "Requirement",
      "AssignedTo": "janed",
      "Status": "Draft",
      "Priority": "Medium",
      "Type": "Functional",
      "PackageId": "454bc5ca-3496-4abb-a69a-919bf5f3ca0b",
      "PackageName": "Cycle 1",
      "PackageEntityType": "RequirementPackage",
      "PackagePath": "/Requirements/Cycle 1",
      "RelationshipId": null,
      "RelationshipTypeKey": "ScriptToRequirementCoverage",
      "RelationshipType": "Coverage",
      "Relation": "Covered By",
      "RelationshipDirection": "Destination -> Source",
      "CanDelete": false,
      "CanEdit": true,
      "Children": [],
      "Links": [
        {
          "Href": "http://localhost/api",
          "Rel": "Entity"
        }
      ]
    }
  ],
  "Links": [
    {
      "Href": "http://localhost/api",
      "Rel": "Entity"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test Assignment ( /api/automatedtestassignment/{id} )

Automated Test Assignment resource

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Delete automated test assignment by it's unique Identifier

Required Permissions

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if the required permissions to delete this automated test assignment have not been met.
404 - NotFoundReturned if no automated test assignment with the specified identifier exists.

Example - Delete Assignment

Example of deleting an automated test assignment.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of the automated test assignment to delete.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves a single automated test assignment by its unique identifier.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request is completed successfully.
403 - ForbiddenReturned if the required permission to view this automated test assignment have not been met.
404 - NotFoundReturned if no automated test assignment with the specified identifier exists.

Example - GET

Example of retrieving a automated test assignment

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of assignment to retrieve.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "AutomatedTestId": "5ef6c545-6ef8-472e-bae7-b1cc3d3fbab0",
  "Name": "My Test",
  "Status": "Not Run",
  "AssignedTo": null,
  "AssignedToId": null,
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "Expands": [
    "Package"
  ],
  "Self": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/5ef6c545-6ef8-472e-bae7-b1cc3d3fbab0",
      "Rel": "AutomatedTest"
    },
    {
      "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Rel": "ExecutionPackage"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/runs",
      "Rel": "Runs"
    }
  ]
}

Status Code

200 - OK

PUT


Update automated test assignment

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the automated test assignment has been updated successfully.
403 - ForbiddenReturned if the request could not be completed successfuly (normally due to lack of permissions or validation failure).

Example - PUT (update package for the automated test assignment)

Updating the package that the automated test assignment belongs to.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of package to delete.

Request Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "AutomatedTestId": "888f8e22-0137-440a-bcf2-173b9d6f543f"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "AutomatedTestId": "888f8e22-0137-440a-bcf2-173b9d6f543f",
  "Name": "My Test",
  "Status": "Not Run",
  "AssignedTo": null,
  "AssignedToId": null,
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "Expands": [
    "Package"
  ],
  "Self": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/888f8e22-0137-440a-bcf2-173b9d6f543f",
      "Rel": "AutomatedTest"
    },
    {
      "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Rel": "ExecutionPackage"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/runs",
      "Rel": "Runs"
    }
  ]
}

Status Code

200 - OK

Example - PUT (assign automated test assignment to user)

Updating a automated test assignment to be assigned to a new user (this does not change the tester for any active script runs associated with this assignment).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of the package to delete.

Request Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "AssignedToId": "203f8f8a-20a7-40ff-bb9c-dbed4fcfcd98",
  "AutomatedTestId": "888f8e22-0137-440a-bcf2-173b9d6f543f"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "AutomatedTestId": "888f8e22-0137-440a-bcf2-173b9d6f543f",
  "Name": "My Test",
  "Status": "Not Run",
  "AssignedTo": "joeb",
  "AssignedToId": "203f8f8a-20a7-40ff-bb9c-dbed4fcfcd98",
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "Expands": [
    "Package"
  ],
  "Self": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/888f8e22-0137-440a-bcf2-173b9d6f543f",
      "Rel": "AutomatedTest"
    },
    {
      "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Rel": "ExecutionPackage"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/runs",
      "Rel": "Runs"
    }
  ]
}

Status Code

200 - OK

Example - PUT (unassign a previously assigned script)

Updating an automated test assignment to be unassigned (A null value cannot be passed because this will be ignored, due the implementation of partial updates. An empty GUID will be passed instead.)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of the package to delete.

Request Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "AssignedToId": "00000000-0000-0000-0000-000000000000",
  "AutomatedTestId": "888f8e22-0137-440a-bcf2-173b9d6f543f"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "AutomatedTestId": "888f8e22-0137-440a-bcf2-173b9d6f543f",
  "Name": "My Test",
  "Status": "Not Run",
  "AssignedTo": null,
  "AssignedToId": null,
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "Expands": [
    "Package"
  ],
  "Self": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/888f8e22-0137-440a-bcf2-173b9d6f543f",
      "Rel": "AutomatedTest"
    },
    {
      "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Rel": "ExecutionPackage"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/runs",
      "Rel": "Runs"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test Assignment All Relationships ( /api/automatedtestassignment/{id}/allrelationships )

A resource representing the set of relationships belonging to the Automated Test Assignment (includes the full graph of related entities, not just those which can be reached through destination and source->destination directed relationships).

This resource supports the following methods: GET

Methods

GET


Retrieves all relationships

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the relationships associated with this entity.
404 - NotFoundReturned if the entity does not exist.

Example - Retrieve Relationships

Retrieve relationships (the response is a generic example, and does not necessarily represent the type of relationships that would be returned for this Entity Type).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}5E2814AF-1800-4C8F-B7C8-2ED9FADF98D0The ID of the entity to retrieve the relationships for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "EntityId": "8F00D2CE-6243-4956-AF89-60B7B9755A9B",
  "Number": "1",
  "Name": "Some Script",
  "EntityType": "TestScript",
  "AssignedTo": "joeb",
  "Status": "Draft",
  "Priority": "High",
  "Type": "Functional",
  "PackageId": "c232382b-0c66-475b-b59b-8753d4c5377b",
  "PackageName": "Cycle 1",
  "PackageEntityType": "ScriptPackage",
  "PackagePath": "/Script Library/Cycle 1",
  "RelationshipId": null,
  "RelationshipTypeKey": "ScriptToRequirementCoverage",
  "RelationshipType": "Coverage",
  "Relation": "Covered By",
  "RelationshipDirection": "Source -> Destination",
  "CanDelete": true,
  "CanEdit": false,
  "Children": [
    {
      "EntityId": "4155F037-B778-4E9D-B942-0CC237D51038",
      "Number": "2",
      "Name": "Some Requirement",
      "EntityType": "Requirement",
      "AssignedTo": "janed",
      "Status": "Draft",
      "Priority": "Medium",
      "Type": "Functional",
      "PackageId": "454bc5ca-3496-4abb-a69a-919bf5f3ca0b",
      "PackageName": "Cycle 1",
      "PackageEntityType": "RequirementPackage",
      "PackagePath": "/Requirements/Cycle 1",
      "RelationshipId": null,
      "RelationshipTypeKey": "ScriptToRequirementCoverage",
      "RelationshipType": "Coverage",
      "Relation": "Covered By",
      "RelationshipDirection": "Destination -> Source",
      "CanDelete": false,
      "CanEdit": true,
      "Children": [],
      "Links": [
        {
          "Href": "http://localhost/api",
          "Rel": "Entity"
        }
      ]
    }
  ],
  "Links": [
    {
      "Href": "http://localhost/api",
      "Rel": "Entity"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test Assignment Relationships ( /api/automatedtestassignment/{id}/relationships )

A resource representing the set of relationships belonging to the Automated Test Assignment.

This resource supports the following methods: GET

Methods

GET


Retrieves all relationships

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the relationships associated with this entity.
404 - NotFoundReturned if the entity does not exist.

Example - Retrieve Relationships

Retrieve relationships (the response is a generic example, and does not necessarily represent the type of relationships that would be returned for this Entity Type).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}5E2814AF-1800-4C8F-B7C8-2ED9FADF98D0The ID of the entity to retrieve the relationships for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "EntityId": "8F00D2CE-6243-4956-AF89-60B7B9755A9B",
  "Number": "1",
  "Name": "Some Script",
  "EntityType": "TestScript",
  "AssignedTo": "joeb",
  "Status": "Draft",
  "Priority": "High",
  "Type": "Functional",
  "PackageId": "c232382b-0c66-475b-b59b-8753d4c5377b",
  "PackageName": "Cycle 1",
  "PackageEntityType": "ScriptPackage",
  "PackagePath": "/Script Library/Cycle 1",
  "RelationshipId": null,
  "RelationshipTypeKey": "ScriptToRequirementCoverage",
  "RelationshipType": "Coverage",
  "Relation": "Covered By",
  "RelationshipDirection": "Source -> Destination",
  "CanDelete": true,
  "CanEdit": false,
  "Children": [
    {
      "EntityId": "4155F037-B778-4E9D-B942-0CC237D51038",
      "Number": "2",
      "Name": "Some Requirement",
      "EntityType": "Requirement",
      "AssignedTo": "janed",
      "Status": "Draft",
      "Priority": "Medium",
      "Type": "Functional",
      "PackageId": "454bc5ca-3496-4abb-a69a-919bf5f3ca0b",
      "PackageName": "Cycle 1",
      "PackageEntityType": "RequirementPackage",
      "PackagePath": "/Requirements/Cycle 1",
      "RelationshipId": null,
      "RelationshipTypeKey": "ScriptToRequirementCoverage",
      "RelationshipType": "Coverage",
      "Relation": "Covered By",
      "RelationshipDirection": "Destination -> Source",
      "CanDelete": false,
      "CanEdit": true,
      "Children": [],
      "Links": [
        {
          "Href": "http://localhost/api",
          "Rel": "Entity"
        }
      ]
    }
  ],
  "Links": [
    {
      "Href": "http://localhost/api",
      "Rel": "Entity"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test Assignment Runs ( /api/automatedtestassignment/{id}/runs )

A collection resource that can be used for creating new automated test assignment runs from a test results file via POST request, or retrieving the list of existing runs

This resource supports the following methods: GET, POST

Methods

GET


Retrieves the set of runs associated with the automated test assignment

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if you do not have permission to view the test assignment.
404 - NotFoundReturned if automated test assignment does not exist.

Example - Retrieve all runs

Retrieve all runs of automated test assignment

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}FC68461E-5921-4240-BB8B-2D00549D923AUnique identifier of automated test assignment

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "RunByDisplayName": "joeb",
      "RunBy": "joeb",
      "RunById": "7564ff5c-7e17-4e05-a06c-9e6e64bf2afc",
      "AssignmentId": "00000000-0000-0000-0000-000000000000",
      "Id": "a4257c03-7c3c-47c8-a637-ba3927b6b127",
      "Status": "Failed",
      "ImportedAt": "2012-01-03T23:00:00Z",
      "StartedAt": "2012-01-01T14:04:05Z",
      "FinishedAt": "2012-01-02T15:05:06Z",
      "Self": "http://localhost/api/automatedtestrun/a4257c03-7c3c-47c8-a637-ba3927b6b127"
    },
    {
      "RunByDisplayName": "joeb",
      "RunBy": "joeb",
      "RunById": "7564ff5c-7e17-4e05-a06c-9e6e64bf2afc",
      "AssignmentId": "00000000-0000-0000-0000-000000000000",
      "Id": "d3996027-1672-43e2-9c1f-6b4e74a5b12b",
      "Status": "Failed",
      "ImportedAt": "2012-02-03T23:00:00Z",
      "StartedAt": "2012-02-02T15:05:06Z",
      "FinishedAt": "2012-02-02T16:00:00Z",
      "Self": "http://localhost/api/automatedtestrun/d3996027-1672-43e2-9c1f-6b4e74a5b12b"
    }
  ]
}

Status Code

200 - OK

POST


Creates a new automated test run, via an upload or by pointing to a results file

Required Permissions

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
200 - OKReturned if request completed successfully.

Example - Mime multipart file upload

Import via a file upload

Request Headers

KeyValueDescription
Content-Typemultipart/mixed; boundary=65bf6b94-c91c-442c-abe7-f41444d7c71f

Request Parameters

KeyValueDescription
{id}E0B7E86E-86F2-43BE-83CC-8309C07F3F38Unique identifier of the automated test assignment

Request Body

------65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: form-data; name="fileUpload"; filename="NUnit.xml"
Content-Type: text/xml
...
------65bf6b94-c91c-442c-abe7-f41444d7c71f--

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Complete": false,
  "TotalElements": 0,
  "ProcessedElements": 0,
  "StartedAt": "2012-07-04T10:58:22Z",
  "ProgressInPercent": 0.0,
  "Id": "automatedtestimport_a7505ca4-1658-404e-b458-9cc9e5d0a219",  
  "Self": "http://localhost/EnterpriseTester/api/backgroundtask/automatedtestimport_a7505ca4-1658-404e-b458-9cc9e5d0a219"
}

Status Code

202 - Accepted

Example - POST - via on-server file

Import results via an on-server file

Request Headers

KeyValueDescription
Content-Typemultipart/mixed; boundary=65bf6b94-c91c-442c-abe7-f41444d7c71f

Request Parameters

KeyValueDescription
{id}E0B7E86E-86F2-43BE-83CC-8309C07F3F38Unique identifier of the automated test assignment

Request Body

{
    "Parameters": {
        "ResultFile": "D:\\testoutput\\NUnit-simple.xml"
    }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Complete": false,
  "TotalElements": 0,
  "ProcessedElements": 0,
  "StartedAt": "2012-07-04T10:58:22Z",
  "ProgressInPercent": 0.0,
  "Id": "automatedtestimport_a7505ca4-1658-404e-b458-9cc9e5d0a219",  
  "Self": "http://localhost/EnterpriseTester/api/backgroundtask/automatedtestimport_a7505ca4-1658-404e-b458-9cc9e5d0a219"
}

Status Code

202 - Accepted

Resource: Automated Test Assignments ( /api/automatedtestassignments )

Automated Test Assignments collection resource.

Root Relation: AutomatedTestAssignments

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of automated test assignments that are visible associated with the automated test. This method takes a TQL query.

This method supports the TQL query parameters tql, $top, $take and $inlinecount. See TQL Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request is completed successfully.

Example - GET (filtered by TQL Query)

Retrieves automated test assignments matching a TQL query.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
tqlName ~ 'Report'The TQL query to execute.
$top5The Maximum number of results to return (defaults to 25).
$skip0The number of results to skip before return the $top number of results matching the query

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 1,
  "Items": [
    {
      "Id": "3fa6ec13-3939-45b6-beb1-dd03e00a83f9",
      "AutomatedTestId": "c6173eab-f684-4d35-8ca7-62851b8df0e1",
      "Name": "Report output paging",
      "Status": "Not Run",
      "AssignedTo": "joeb",
      "AssignedToId": "b2a74983-e374-41d4-bf49-bc3c9a5f0e89",
      "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Expands": [
        "Package"
      ],
      "Self": "http://localhost/api/automatedtestassignment/3fa6ec13-3939-45b6-beb1-dd03e00a83f9",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtestassignment/3fa6ec13-3939-45b6-beb1-dd03e00a83f9/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/c6173eab-f684-4d35-8ca7-62851b8df0e1",
          "Rel": "AutomatedTest"
        },
        {
          "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
          "Rel": "ExecutionPackage"
        },
        {
          "Href": "http://localhost/api/automatedtestassignment/3fa6ec13-3939-45b6-beb1-dd03e00a83f9/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/automatedtestassignment/3fa6ec13-3939-45b6-beb1-dd03e00a83f9/runs",
          "Rel": "Runs"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/automatedtestassignments?tql=Name~'Report'"
}

Status Code

200 - OK

Example - GET (no TQL query)

Retrieves all automated test assignments, across all projects.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "Id": "3fa6ec13-3939-45b6-beb1-dd03e00a83f9",
      "AutomatedTestId": "c6173eab-f684-4d35-8ca7-62851b8df0e1",
      "Name": "Report output paging",
      "Status": "Not Run",
      "AssignedTo": "joeb",
      "AssignedToId": "b2a74983-e374-41d4-bf49-bc3c9a5f0e89",
      "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Expands": [
        "Package"
      ],
      "Self": "http://localhost/api/automatedtestassignment/3fa6ec13-3939-45b6-beb1-dd03e00a83f9",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtestassignment/3fa6ec13-3939-45b6-beb1-dd03e00a83f9/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/c6173eab-f684-4d35-8ca7-62851b8df0e1",
          "Rel": "AutomatedTest"
        },
        {
          "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
          "Rel": "ExecutionPackage"
        },
        {
          "Href": "http://localhost/api/automatedtestassignment/3fa6ec13-3939-45b6-beb1-dd03e00a83f9/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/automatedtestassignment/3fa6ec13-3939-45b6-beb1-dd03e00a83f9/runs",
          "Rel": "Runs"
        }
      ]
    },
    {
      "Id": "8be49e2e-590c-485e-a713-ef3e8353e1d5",
      "AutomatedTestId": "c6173eab-f684-4d35-8ca7-62851b8df0e1",
      "Name": "Login password minimum length is 6",
      "Status": "Passed",
      "AssignedTo": "joeb",
      "AssignedToId": "b2a74983-e374-41d4-bf49-bc3c9a5f0e89",
      "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Expands": [
        "Package"
      ],
      "Self": "http://localhost/api/automatedtestassignment/8be49e2e-590c-485e-a713-ef3e8353e1d5",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtestassignment/8be49e2e-590c-485e-a713-ef3e8353e1d5/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/c6173eab-f684-4d35-8ca7-62851b8df0e1",
          "Rel": "AutomatedTest"
        },
        {
          "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
          "Rel": "ExecutionPackage"
        },
        {
          "Href": "http://localhost/api/automatedtestassignment/8be49e2e-590c-485e-a713-ef3e8353e1d5/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/automatedtestassignment/8be49e2e-590c-485e-a713-ef3e8353e1d5/runs",
          "Rel": "Runs"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Creates a new automated test assignment.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the automated test assignment is created successfully.
403 - ForbiddenReturned if the request could not be completed successfuly (normally due to lack of permissions or validation failure).

Example - POST (no assignee)

Create a new automated test assignment, with no assignee.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "AutomatedTestId": "5ef6c545-6ef8-472e-bae7-b1cc3d3fbab0"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "AutomatedTestId": "5ef6c545-6ef8-472e-bae7-b1cc3d3fbab0",
  "Name": "My Test",
  "Status": "Not Run",
  "AssignedTo": null,
  "AssignedToId": null,
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "Expands": [
    "Package"
  ],
  "Self": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/5ef6c545-6ef8-472e-bae7-b1cc3d3fbab0",
      "Rel": "AutomatedTest"
    },
    {
      "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Rel": "ExecutionPackage"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/runs",
      "Rel": "Runs"
    }
  ]
}

Status Code

201 - Created

Example - POST (with assignee)

Create a new automated test assignment, with the assignee set.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "AssignedToId": "5bb78013-222a-45a8-b639-ac0ce0a8a505",
  "AutomatedTestId": "5ef6c545-6ef8-472e-bae7-b1cc3d3fbab0"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "AutomatedTestId": "5ef6c545-6ef8-472e-bae7-b1cc3d3fbab0",
  "Name": "My Test",
  "Status": "Not Run",
  "AssignedTo": "joeb",
  "AssignedToId": "5bb78013-222a-45a8-b639-ac0ce0a8a505",
  "PackageId": "f6ed1282-bd89-4f8f-8e94-47e344bba905",
  "Expands": [
    "Package"
  ],
  "Self": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/5ef6c545-6ef8-472e-bae7-b1cc3d3fbab0",
      "Rel": "AutomatedTest"
    },
    {
      "Href": "http://localhost/api/executionpackage/f6ed1282-bd89-4f8f-8e94-47e344bba905",
      "Rel": "ExecutionPackage"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtestassignment/4bb709c2-e0e7-4af3-9f60-a045016a9610/runs",
      "Rel": "Runs"
    }
  ]
}

Status Code

201 - Created

Resource: Automated Test Relationships ( /api/automatedtest/{id}/relationships )

A resource representing the set of relationships belonging to the Automated Test.

This resource supports the following methods: GET

Methods

GET


Retrieves all relationships

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the relationships associated with this entity.
404 - NotFoundReturned if the entity does not exist.

Example - Retrieve Relationships

Retrieve relationships (the response is a generic example, and does not necessarily represent the type of relationships that would be returned for this Entity Type).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}5E2814AF-1800-4C8F-B7C8-2ED9FADF98D0The ID of the entity to retrieve the relationships for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "EntityId": "8F00D2CE-6243-4956-AF89-60B7B9755A9B",
  "Number": "1",
  "Name": "Some Script",
  "EntityType": "TestScript",
  "AssignedTo": "joeb",
  "Status": "Draft",
  "Priority": "High",
  "Type": "Functional",
  "PackageId": "c232382b-0c66-475b-b59b-8753d4c5377b",
  "PackageName": "Cycle 1",
  "PackageEntityType": "ScriptPackage",
  "PackagePath": "/Script Library/Cycle 1",
  "RelationshipId": null,
  "RelationshipTypeKey": "ScriptToRequirementCoverage",
  "RelationshipType": "Coverage",
  "Relation": "Covered By",
  "RelationshipDirection": "Source -> Destination",
  "CanDelete": true,
  "CanEdit": false,
  "Children": [
    {
      "EntityId": "4155F037-B778-4E9D-B942-0CC237D51038",
      "Number": "2",
      "Name": "Some Requirement",
      "EntityType": "Requirement",
      "AssignedTo": "janed",
      "Status": "Draft",
      "Priority": "Medium",
      "Type": "Functional",
      "PackageId": "454bc5ca-3496-4abb-a69a-919bf5f3ca0b",
      "PackageName": "Cycle 1",
      "PackageEntityType": "RequirementPackage",
      "PackagePath": "/Requirements/Cycle 1",
      "RelationshipId": null,
      "RelationshipTypeKey": "ScriptToRequirementCoverage",
      "RelationshipType": "Coverage",
      "Relation": "Covered By",
      "RelationshipDirection": "Destination -> Source",
      "CanDelete": false,
      "CanEdit": true,
      "Children": [],
      "Links": [
        {
          "Href": "http://localhost/api",
          "Rel": "Entity"
        }
      ]
    }
  ],
  "Links": [
    {
      "Href": "http://localhost/api",
      "Rel": "Entity"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test Run ( /api/automatedtestrun/{id} )

Automated Test Run resource

This resource supports the following methods: DELETE, GET

Methods

DELETE


Deletes an automated test run by its unique identifier.

Required Permissions

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if the required permissions to delete this automated test run have not been met.
404 - NotFoundReturned if no automated test run with the specified identifier exists.

Example - DELETE

An example of deleting a automated test run.

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610The unique identifier of the automated test run to delete.

Status Code

200 - OK

GET


Retrieves an automated test run by ID.

This method supports the TQL query parameters tql, $top, $take and $inlinecount. See TQL Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete request (normally due to a validation failure or you don't have the necessary permissions to complete the request).

Example - GET

Retrieves automated test run by identifier.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
id02cbe373-a042-4f7b-8ba3-e03b1588dbfaThe unique identifier of the automated test run.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "RunByDisplayName": "joeb",
  "RunBy": "joeb",
  "RunById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "AssignmentId": "979ce5f8-efb7-432d-8848-c9cdf3151977",
  "Id": "02cbe373-a042-4f7b-8ba3-e03b1588dbfa",
  "Status": "Passed",
  "ImportedAt": "2013-01-16T16:15:00Z",
  "StartedAt": "2013-01-16T15:05:06Z",
  "FinishedAt": "2013-01-15T16:00:00Z",
  "Expands": [
    "Assignment",
    "Totals"
  ],
  "Self": "http://localhost/api/automatedtestrun/02cbe373-a042-4f7b-8ba3-e03b1588dbfa"
}

Status Code

200 - OK

Example - GET (expand Totals)

Retrieves an automated test run with the Totals included.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
id02cbe373-a042-4f7b-8ba3-e03b1588dbfaThe unique identifier of the automated test run.
$expandTotals

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "RunByDisplayName": "joeb",
  "RunBy": "joeb",
  "RunById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "AssignmentId": "979ce5f8-efb7-432d-8848-c9cdf3151977",
  "Id": "02cbe373-a042-4f7b-8ba3-e03b1588dbfa",
  "Status": "Passed",
  "ImportedAt": "2013-01-16T16:15:00Z",
  "StartedAt": "2013-01-16T15:05:06Z",
  "FinishedAt": "2013-01-15T16:00:00Z",
  "Expands": [
    "Assignment"
  ],
  "Totals": {
    "Errors": 0,
    "Failed": 0,
    "Iterations": 0,
    "NotRun": 0,
    "Passed": 10,
    "Skipped": 0,
    "Warnings": 0,
    "Done": 0,
    "Infos": 0,
    "TotalNodes": 10,
    "TotalResults": 10
  },
  "Self": "http://localhost/api/automatedtestrun/02cbe373-a042-4f7b-8ba3-e03b1588dbfa"
}

Status Code

200 - OK

Resource: Automated Test Run Attachment ( /api/automatedtestrun/{runId}/attachment/{attachmentId} )

A resource representing an attachment of an Automated Test Run.

This resource supports the following methods: DELETE

Methods

DELETE


Deletes an attachment from a particular Automated Test Run.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run or the attachment was not found in the database.

Example - DELETE

Deletes an attachment for a particular Automated Test Run.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the Automated Test Run.
{attachmentId}9cb7f1cb-984d-4c47-9275-82d6409ed6beThe unique identifier (GUID) of the Attachment to delete.

Status Code

200 - OK

Resource: Automated Test Run Attachments ( /api/automatedtestrun/{runId}/attachments )

A collection resource representing the attachments of an Automated Test Run.

This resource supports the following methods: GET, POST

Methods

GET


Retrieves a list of attachments for a particular Automated Test Run.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run was not found in the database.

Example - GET

Retrieves a list of attachments for a particular Automated Test Run.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the Automated Test Run.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
    "Id": "9cb7f1cb-984d-4c47-9275-82d6409ed6be",
    "Name": "File 1",
    "FileName": "File 1.txt",
    "ContentType": "text/plain",
    "CreatedAt": "2013-02-01T11:00:00Z",
    "CreatedById": "89fda208-2f7a-42e9-8d0a-3518b80b0765",
    "Size": 111,
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/attachment/9cb7f1cb-984d-4c47-9275-82d6409ed6be",
    "Content": "http://localhost/api/attachment/9cb7f1cb-984d-4c47-9275-82d6409ed6be/contents"
  },
  {
    "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
    "Id": "e6040570-48fb-48b4-af1e-fa90fe4ae7dd",
    "Name": "File 2",
    "FileName": "File 2.txt",
    "ContentType": "text/plain",
    "CreatedAt": "2013-02-01T11:00:00Z",
    "CreatedById": "89fda208-2f7a-42e9-8d0a-3518b80b0765",
    "Size": 148,
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/attachment/e6040570-48fb-48b4-af1e-fa90fe4ae7dd",
    "Content": "http://localhost/api/attachment/e6040570-48fb-48b4-af1e-fa90fe4ae7dd/contents"
  },
  {
    "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
    "Id": "72d41457-1840-4a86-8080-788f3d974ba6",
    "Name": "File 3",
    "FileName": "File 3.txt",
    "ContentType": "text/plain",
    "CreatedAt": "2013-02-01T11:00:00Z",
    "CreatedById": "89fda208-2f7a-42e9-8d0a-3518b80b0765",
    "Size": 185,
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/attachment/72d41457-1840-4a86-8080-788f3d974ba6",
    "Content": "http://localhost/api/attachment/72d41457-1840-4a86-8080-788f3d974ba6/contents"
  }
]

Status Code

200 - OK

POST


Adds a new attachment to a particular Automated Test Run.

Required Permissions

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
201 - CreatedReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run was not found in the database.
415 - UnsupportedMediaTypeReturned if the request is not mime multipart.

Example - POST

Adds a new attachment to a particular Automated Test Run.

Request Headers

KeyValueDescription
Content-Typemultipart/mixed; boundary=65bf6b94-c91c-442c-abe7-f41444d7c71f

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the Automated Test Run.

Request Body

--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename=screenshot1.png; name="screenshot 1"; size=122454
Content-Type: image/png
Content-Length: 3
...
--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename=notes.txt; name=notes; size=3
Content-Type: text/plain
Content-Length: 3
ABC
--65bf6b94-c91c-442c-abe7-f41444d7c71f--

Response Headers

KeyValueDescription
Locationhttp://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/attachmentsThe location of the new attachment resource

Status Code

201 - Created

Resource: Automated Test Run Data ( /api/automatedtestrun/{id}/testdata )

A resource representing the data of an Automated Test Run.

This resource supports the following methods: GET

Methods

GET


Retrieves the data for a particular Automated Test Run.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run was not found in the database.

Example - GET

Retrieves the data for a particular Automated Test Run.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}5cd9987f-c4c6-400e-a3a3-95f7997be00aThe unique identifier (GUID) of the Automated Test Run.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Tables": [
    {
      "Name": "People",
      "ColumnNames": [
        "Age",
        "Id",
        "Name"
      ],
      "Rows": [
        {
          "Id": "1",
          "Name": "Joe",
          "Age": "33",
          "__row_number": "0"
        },
        {
          "Id": "2",
          "Name": "John",
          "Age": "45",
          "__row_number": "1"
        }
      ]
    },
    {
      "Name": "Jobs",
      "ColumnNames": [
        "Id",
        "Name"
      ],
      "Rows": [
        {
          "Id": "1",
          "Name": "Baker",
          "__row_number": "0"
        },
        {
          "Id": "2",
          "Name": "Butcher",
          "__row_number": "1"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/automatedtestrun/5cd9987f-c4c6-400e-a3a3-95f7997be00a/testdata"
}

Status Code

200 - OK

Resource: Automated Test Run Incident ( /api/automatedtestrun/{runId}/node/{nodeId}/incident/{incidentId} )

A resource representing an incident link of an automated test run.

This resource supports the following methods: DELETE, GET

Methods

DELETE


Deletes an incident link from a particular automated test run.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run, node or incident was not found in the database, or if the link didn't exist.

Example - DELETE

Deletes an incident from a particular automated test run.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the automated test run.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe unique identifier (GUID) of the automated test run result node.
{incidentId}5a5be006-ba7b-4c45-b3a8-ce8d793066ddThe unique identifier (GUID) of the incident.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves a particular incident for an automated test run.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run, node or incident was not found in the database.

Example - GET

Retrieves a particular incident for a automated test run.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the automated test run.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe unique identifier (GUID) of the automated test run result node.
{incidentId}5a5be006-ba7b-4c45-b3a8-ce8d793066ddThe unique identifier (GUID) of the incident.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
  "NodeId": "b8166143-c269-4bd8-876e-d2584edc4e2e",
  "IncidentId": "5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
  "Expands": [
    "Run",
    "Node",
    "Incident"
  ],
  "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/b8166143-c269-4bd8-876e-d2584edc4e2e/incident/5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
  "Links": [
    {
      "Href": "http://localhost/api/incident/5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
      "Rel": "Incident"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test Run Incidents ( /api/automatedtestrun/{runId}/node/{nodeId}/incidents )

A collection resource representing the incident links of an automated test run.

This resource supports the following methods: GET, POST

Methods

GET


Retrieves the incidents for a particular automated test run.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run or node was not found in the database.

Example - GET

Retrieves a list of incidents for a particular automated test run.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the automated test run.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe unique identifier (GUID) of the automated test run result node.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
      "NodeId": "b8166143-c269-4bd8-876e-d2584edc4e2e",
      "IncidentId": "5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
      "Expands": [
        "Run",
        "Node",
        "Incident"
      ],
      "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/b8166143-c269-4bd8-876e-d2584edc4e2e/incident/5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
      "Links": [
        {
          "Href": "http://localhost/api/incident/5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
          "Rel": "Incident"
        }
      ]
    },
    {
      "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
      "NodeId": "b8166143-c269-4bd8-876e-d2584edc4e2e",
      "IncidentId": "02b6a3f5-121c-4900-8d10-16604ed2c297",
      "Expands": [
        "Run",
        "Node",
        "Incident"
      ],
      "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/b8166143-c269-4bd8-876e-d2584edc4e2e/incident/02b6a3f5-121c-4900-8d10-16604ed2c297",
      "Links": [
        {
          "Href": "http://localhost/api/incident/02b6a3f5-121c-4900-8d10-16604ed2c297",
          "Rel": "Incident"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Adds an incident link to a particular automated test run.

Required Permissions

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
201 - CreatedReturned if the request was completed successfully.
400 - BadRequestReturned if the POST data was incorrect.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run, node or incident was not found in the database.

Example - POST

Adds a new incident to a particular automated test run.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the automated test run.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe unique identifier (GUID) of the automated test run result node.

Request Body

{
  "IncidentId": "5a5be006-ba7b-4c45-b3a8-ce8d793066dd"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/b8166143-c269-4bd8-876e-d2584edc4e2e/incident/5a5be006-ba7b-4c45-b3a8-ce8d793066ddThe location of the new incident resource.

Response Body

{
  "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
  "NodeId": "b8166143-c269-4bd8-876e-d2584edc4e2e",
  "IncidentId": "5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
  "Expands": [
    "Run",
    "Node",
    "Incident"
  ],
  "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/b8166143-c269-4bd8-876e-d2584edc4e2e/incident/5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
  "Links": [
    {
      "Href": "http://localhost/api/incident/5a5be006-ba7b-4c45-b3a8-ce8d793066dd",
      "Rel": "Incident"
    }
  ]
}

Status Code

201 - Created

Resource: Automated Test Run Node Attachment ( /api/automatedtestrun/{runId}/node/{nodeId}/attachment/{attachmentId} )

A resource representing an attachment of an Automated Test Run Result Node.

This resource supports the following methods: DELETE

Methods

DELETE


Deletes an attachment from a particular Automated Test Run's Result Node.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run, node or attachment was not found in the database.

Example - DELETE

Deletes an attachment for a particular Automated Test Run's result node.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the Automated Test Run.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe unique identifier (GUID) of the Automated Test Run Result Node.
{attachmentId}9cb7f1cb-984d-4c47-9275-82d6409ed6beThe unique identifier (GUID) of the Attachment to delete.

Status Code

200 - OK

Resource: Automated Test Run Node Attachments ( /api/automatedtestrun/{runId}/node/{nodeId}/attachments )

A collection resource representing the attachments of an Automated Test Run Result Node.

This resource supports the following methods: GET, POST

Methods

GET


Retrieves a list of attachments for a particular Automated Test Run's Result Node.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run or the node was not found in the database.

Example - GET

Retrieves a list of attachments for a particular Automated Test Run's result node.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the Automated Test Run.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe unique identifier (GUID) of the Automated Test Run Result Node.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "NodeId": "b8166143-c269-4bd8-876e-d2584edc4e2e",
    "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
    "Id": "9cb7f1cb-984d-4c47-9275-82d6409ed6be",
    "Name": "File 1",
    "FileName": "File 1.txt",
    "ContentType": "text/plain",
    "CreatedAt": "2013-02-01T11:00:00Z",
    "CreatedById": "89fda208-2f7a-42e9-8d0a-3518b80b0765",
    "Size": 111,
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/b8166143-c269-4bd8-876e-d2584edc4e2e/attachment/9cb7f1cb-984d-4c47-9275-82d6409ed6be",
    "Content": "http://localhost/api/attachment/9cb7f1cb-984d-4c47-9275-82d6409ed6be/contents"
  },
  {
    "NodeId": "b8166143-c269-4bd8-876e-d2584edc4e2e",
    "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
    "Id": "e6040570-48fb-48b4-af1e-fa90fe4ae7dd",
    "Name": "File 2",
    "FileName": "File 2.txt",
    "ContentType": "text/plain",
    "CreatedAt": "2013-02-01T11:00:00Z",
    "CreatedById": "89fda208-2f7a-42e9-8d0a-3518b80b0765",
    "Size": 148,
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/b8166143-c269-4bd8-876e-d2584edc4e2e/attachment/e6040570-48fb-48b4-af1e-fa90fe4ae7dd",
    "Content": "http://localhost/api/attachment/e6040570-48fb-48b4-af1e-fa90fe4ae7dd/contents"
  },
  {
    "NodeId": "b8166143-c269-4bd8-876e-d2584edc4e2e",
    "RunId": "1459858c-9526-412e-afdd-09415593c2d3",
    "Id": "72d41457-1840-4a86-8080-788f3d974ba6",
    "Name": "File 3",
    "FileName": "File 3.txt",
    "ContentType": "text/plain",
    "CreatedAt": "2013-02-01T11:00:00Z",
    "CreatedById": "89fda208-2f7a-42e9-8d0a-3518b80b0765",
    "Size": 185,
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/b8166143-c269-4bd8-876e-d2584edc4e2e/attachment/72d41457-1840-4a86-8080-788f3d974ba6",
    "Content": "http://localhost/api/attachment/72d41457-1840-4a86-8080-788f3d974ba6/contents"
  }
]

Status Code

200 - OK

POST


Adds a new attachment to a particular Automated Test Run's Result Node.

Required Permissions

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
201 - CreatedReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run or the node was not found in the database.
415 - UnsupportedMediaTypeReturned if the request is not mime multipart.

Example - POST

Adds a new attachment to a particular Automated Test Run's result node.

Request Headers

KeyValueDescription
Content-Typemultipart/mixed; boundary=65bf6b94-c91c-442c-abe7-f41444d7c71f

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the Automated Test Run.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe unique identifier (GUID) of the Automated Test Run Result Node.

Request Body

--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename=screenshot1.png; name="screenshot 1"; size=122454
Content-Type: image/png
Content-Length: 3
...
--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename=notes.txt; name=notes; size=3
Content-Type: text/plain
Content-Length: 3
ABC
--65bf6b94-c91c-442c-abe7-f41444d7c71f--

Response Headers

KeyValueDescription
Locationhttp://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/attachmentsThe location of the new attachment resource

Status Code

201 - Created

Resource: Automated Test Run Result Children ( /api/automatedtestrun/{runId}/node/{nodeId}/children )

A collection resource representing the child result ndes of an Automated Test Run Result node.

This resource supports the following methods: GET

Methods

GET


Retrieves the children of a particular automated test run result node. This collection can optionally be filtered by outcome/status. Passing an empty GUID for the node ID will return the root nodes in a run.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
400 - BadRequestReturned if the status filter included an invalid status.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run or the node was not found in the database.

Example - GET

Retrieves run result children by parent node ID.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the run to get results for.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe parent node unique identifier (GUID) to find children for (or an empty GUID to find root nodes).

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": true,
    "Id": "a1d456c4-3713-4f5e-906b-8d56fd977aa2",
    "Name": "Passing test run node",
    "Description": "A node that passes",
    "Notes": null,
    "Status": "Passed",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children",
      "Metadata",
      "Parameters"
    ],
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/a1d456c4-3713-4f5e-906b-8d56fd977aa2"
  },
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": false,
    "Id": "8b34026c-260e-4a8c-8bc5-60df88cf1c27",
    "Name": "Failed test run node",
    "Description": "A node that's failed",
    "Notes": null,
    "Status": "Failed",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children",
      "Metadata",
      "Parameters"
    ],
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/8b34026c-260e-4a8c-8bc5-60df88cf1c27"
  },
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": false,
    "Id": "12a4c6ad-5c99-4f61-974b-723543cb167c",
    "Name": "Not run test run node",
    "Description": "A node that's not been run",
    "Notes": null,
    "Status": "NotRun",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children",
      "Metadata",
      "Parameters"
    ],
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/12a4c6ad-5c99-4f61-974b-723543cb167c"
  }
]

Status Code

200 - OK

Example - GET with statuses filter

Retrieves run result children by parent node ID, including only nodes that have (or with descendants that have) one of the specified statuses.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the run to get results for.
{nodeId}b8166143-c269-4bd8-876e-d2584edc4e2eThe parent node unique identifier (GUID) to find children for (or an empty GUID to find root nodes).
statusesPassed,DoneA comma separated list of statuses to filter by. Valid statuses are: Passed, Failed, Done, Warning, Information, Skipped, Error and NotRun.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": true,
    "Id": "a1d456c4-3713-4f5e-906b-8d56fd977aa2",
    "Name": "Passing test run node",
    "Description": "A node that passes",
    "Notes": null,
    "Status": "Passed",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children",
      "Metadata",
      "Parameters"
    ],
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/a1d456c4-3713-4f5e-906b-8d56fd977aa2"
  }
]

Status Code

200 - OK

Resource: Automated Test Run Result Node ( /api/automatedtestrun/{runId}/node/{nodeId} )

Represents a single automated test result node, which can be either retrieved or updated.

This resource supports the following methods: GET, PATCH

Methods

GET


Retrieves a result node of an automated test run by node ID.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run or the node was not found in the database.

Example - GET

Retrieves run result nodes by ID.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the run to get results for.
{nodeId}a1d456c4-3713-4f5e-906b-8d56fd977aa2The node unique identifier (GUID) to find.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": true,
    "Id": "a1d456c4-3713-4f5e-906b-8d56fd977aa2",
    "Name": "Passing test run node",
    "Description": "A node that passes",
    "Notes": null,
    "Status": "Passed",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children"
    ],
    "Metadata": {
      "ApplicationDir": "C:\\Program Files (x86)\\HP\\QuickTest Professional",
      "ApplicationPath": "\\samples\\flight\\app\\flight4a.exe"
    },
    "Parameters": {
      "Disp": "OpenApplication [FlightLib] Summary",
      "ElementName": "Action"
    },
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/a1d456c4-3713-4f5e-906b-8d56fd977aa2"
  }
]

Status Code

200 - OK

PATCH


Patches a result node of an automated test run by node ID (allows updating of the Notes field associated with a result node).

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run or the node was not found in the database.

Example - PATCH

Update the Notes field of an existing result node.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the run to get results for.
{nodeId}a1d456c4-3713-4f5e-906b-8d56fd977aa2The node unique identifier (GUID) to find.

Request Body

{
  "Notes": "This test fails if run after 3pm"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": true,
    "Id": "a1d456c4-3713-4f5e-906b-8d56fd977aa2",
    "Name": "Passing test run node",
    "Description": "A node that passes",
    "Notes": "This test fails if run after 3pm",
    "Status": "Passed",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children",
      "Metadata",
      "Parameters"
    ],
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/a1d456c4-3713-4f5e-906b-8d56fd977aa2"
  }
]

Status Code

200 - OK

Resource: Automated Test Run Result Root Nodes ( /api/automatedtestrun/{runId}/nodes )

Gets the root result nodes of an Automated Test Run.

This resource supports the following methods: GET

Methods

GET


Retrieves the root result nodes of an automated test run.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the ID for the run was not found in the database.

Example - GET

Retrieves root run result nodes.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{runId}1459858c-9526-412e-afdd-09415593c2d3The unique identifier (GUID) of the run to get results for.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": true,
    "Id": "a1d456c4-3713-4f5e-906b-8d56fd977aa2",
    "Name": "Passing test run node",
    "Description": "A node that passes",
    "Notes": null,
    "Status": "Passed",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children"
    ],
    "Metadata": {
      "ApplicationDir": "C:\\Program Files (x86)\\HP\\QuickTest Professional",
      "ApplicationPath": "\\samples\\flight\\app\\flight4a.exe"
    },
    "Parameters": {
      "Disp": "OpenApplication [FlightLib] Summary",
      "ElementName": "Action"
    },
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/a1d456c4-3713-4f5e-906b-8d56fd977aa2"
  },
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": false,
    "Id": "8b34026c-260e-4a8c-8bc5-60df88cf1c27",
    "Name": "Failed test run node",
    "Description": "A node that's failed",
    "Notes": null,
    "Status": "Failed",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children"
    ],
    "Metadata": {
      "ApplicationDir": "C:\\Program Files (x86)\\HP\\QuickTest Professional",
      "ApplicationPath": "\\samples\\flight\\app\\flight4a.exe"
    },
    "Parameters": {
      "Disp": "OpenApplication [FlightLib] Summary",
      "ElementName": "Action"
    },
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/8b34026c-260e-4a8c-8bc5-60df88cf1c27"
  },
  {
    "HasAttachments": false,
    "HasIncidents": false,
    "HasChildren": false,
    "Id": "12a4c6ad-5c99-4f61-974b-723543cb167c",
    "Name": "Not run test run node",
    "Description": "A node that's not been run",
    "Notes": null,
    "Status": "NotRun",
    "Iteration": 5,
    "StartedAt": "2008-12-25T01:24:00Z",
    "FinishedAt": "2008-12-25T01:29:00Z",
    "DurationInSeconds": 300.0,
    "Expands": [
      "Children"
    ],
    "Metadata": {
      "ApplicationDir": "C:\\Program Files (x86)\\HP\\QuickTest Professional",
      "ApplicationPath": "\\samples\\flight\\app\\flight4a.exe"
    },
    "Parameters": {
      "Disp": "OpenApplication [FlightLib] Summary",
      "ElementName": "Action"
    },
    "Self": "http://localhost/api/automatedtestrun/1459858c-9526-412e-afdd-09415593c2d3/node/12a4c6ad-5c99-4f61-974b-723543cb167c"
  }
]

Status Code

200 - OK

Resource: Automated Test Runs ( /api/automatedtestruns )

Automated Test Runs collection resource.

Root Relation: AutomatedTestRuns

This resource supports the following methods: GET

Methods

GET


Retrieves all (or a subset) of automated test runs that are visible to the user.

This method supports the TQL query parameters tql, $top, $take and $inlinecount. See TQL Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET would not complete request (normally due to a validation failure or you don't have the necessary permissions to complete the request).

Example - GET (filtered by TQL Query)

Retrieves automated test runs matching a TQL query.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
tqlStatus = PassedThe TQL query to execute.
$top5The maximum number of results to return (defaults to 25).
$skip0The number of results to skip before return the $top number of results matching the query.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 1,
  "Items": [
    {
      "RunByDisplayName": "joeb",
      "RunBy": "joeb",
      "RunById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "AssignmentId": "979ce5f8-efb7-432d-8848-c9cdf3151977",
      "Id": "02cbe373-a042-4f7b-8ba3-e03b1588dbfa",
      "Status": "Passed",
      "ImportedAt": "2013-01-16T16:15:00Z",
      "StartedAt": "2013-01-16T15:05:06Z",
      "FinishedAt": "2013-01-15T16:00:00Z",
      "Expands": [
        "Assignment",
        "Totals"
      ],
      "Self": "http://localhost/api/automatedtestrun/02cbe373-a042-4f7b-8ba3-e03b1588dbfa"
    }
  ],
  "Self": "http://localhost/api/api/automatedtestruns?tql=Status=Passed&$top=5&$skip=0"
}

Status Code

200 - OK

Example - GET (no filter)

Retrieves all automated test runs

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$top5The maximum number of results to return (defaults to 25).
$skip0The number of results to skip before return the $top number of results matching the query.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 2,
  "Items": [
    {
      "RunByDisplayName": "joeb",
      "RunBy": "joeb",
      "RunById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "AssignmentId": "979ce5f8-efb7-432d-8848-c9cdf3151977",
      "Id": "02cbe373-a042-4f7b-8ba3-e03b1588dbfa",
      "Status": "Passed",
      "ImportedAt": "2013-01-16T16:15:00Z",
      "StartedAt": "2013-01-16T15:05:06Z",
      "FinishedAt": "2013-01-15T16:00:00Z",
      "Expands": [
        "Assignment",
        "Totals"
      ],
      "Self": "http://localhost/api/automatedtestrun/02cbe373-a042-4f7b-8ba3-e03b1588dbfa"
    },
    {
      "RunByDisplayName": "joeb",
      "RunBy": "joeb",
      "RunById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "AssignmentId": "979ce5f8-efb7-432d-8848-c9cdf3151977",
      "Id": "02cbe373-a042-4f7b-8ba3-e03b1588dbfa",
      "Status": "Failed",
      "ImportedAt": "2013-01-17T16:15:00Z",
      "StartedAt": "2013-01-17T15:05:06Z",
      "FinishedAt": "2013-01-17T16:06:00Z",
      "Expands": [
        "Assignment",
        "Totals"
      ],
      "Self": "http://localhost/api/automatedtestrun/02cbe373-a042-4f7b-8ba3-e03b1588dbfa"
    }
  ],
  "Self": "http://localhost/api/api/automatedtestruns?$top=5&$skip=0"
}

Status Code

200 - OK

Example - GET (no filter) with Totals expanded

Retrieves all automated test runs, including Totals

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$top5The maximum number of results to return (defaults to 25).
$skip0The number of results to skip before return the $top number of results matching the query.
$expandTotals

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 2,
  "Items": [
    {
      "RunByDisplayName": "joeb",
      "RunBy": "joeb",
      "RunById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "AssignmentId": "979ce5f8-efb7-432d-8848-c9cdf3151977",
      "Id": "02cbe373-a042-4f7b-8ba3-e03b1588dbfa",
      "Status": "Passed",
      "ImportedAt": "2013-01-16T16:15:00Z",
      "StartedAt": "2013-01-16T15:05:06Z",
      "FinishedAt": "2013-01-15T16:00:00Z",
      "Expands": [
        "Assignment"
      ],
      "Totals": {
        "Errors": 0,
        "Failed": 0,
        "Iterations": 0,
        "NotRun": 0,
        "Passed": 10,
        "Skipped": 0,
        "Warnings": 0,
        "Done": 0,
        "Infos": 0,
        "TotalNodes": 10,
        "TotalResults": 10
      },
      "Self": "http://localhost/api/automatedtestrun/02cbe373-a042-4f7b-8ba3-e03b1588dbfa"
    },
    {
      "RunByDisplayName": "joeb",
      "RunBy": "joeb",
      "RunById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "AssignmentId": "979ce5f8-efb7-432d-8848-c9cdf3151977",
      "Id": "02cbe373-a042-4f7b-8ba3-e03b1588dbfa",
      "Status": "Failed",
      "ImportedAt": "2013-01-17T16:15:00Z",
      "StartedAt": "2013-01-17T15:05:06Z",
      "FinishedAt": "2013-01-17T16:06:00Z",
      "Expands": [
        "Assignment"
      ],
      "Totals": {
        "Errors": 2,
        "Failed": 0,
        "Iterations": 0,
        "NotRun": 0,
        "Passed": 0,
        "Skipped": 8,
        "Warnings": 0,
        "Done": 0,
        "Infos": 0,
        "TotalNodes": 10,
        "TotalResults": 10
      },
      "Self": "http://localhost/api/automatedtestrun/02cbe373-a042-4f7b-8ba3-e03b1588dbfa"
    }
  ],
  "Self": "http://localhost/api/api/automatedtestruns?$expand=Totals&$top=5&$skip=0"
}

Status Code

200 - OK

Resource: Automated Test Schedule ( /api/automatedtestschedule/{id} )

Automated Test Schedule resource

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Deletes an existing automated test schedule.

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if you do not have permission to delete the schedule.
404 - NotFoundReturned if the automated test schedule does not exist.

Example - DELETE

Delete a schedule (including all it's schedule and import configurations)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}B7C458E9-D207-4998-BAD0-3AFF0E6FA365ID of the schedule to delete

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves an automated test schedule by its unique identifier.

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
200 - OKReturned if request completed successfully.
404 - NotFoundReturned if the automated test schedule does not exist.

Example - GET

Get details for a schedule

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}B7C458E9-D207-4998-BAD0-3AFF0E6FA365ID of the schedule to retrieve

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Name": "Unit Tests",
  "ProjectId": "42b9a01e-8a84-462c-adb9-3f96d3d7de52",
  "ProjectName": "Project XYZ",
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/configurations",
      "Rel": "ScheduleConfigurations"
    }
  ]
}

Status Code

200 - OK

PUT


Updates an existing automated test schedule.

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if the automated test schedule configuration was invalid.
404 - NotFoundReturned if the automated test schedule does not exist.

Example - PUT

Rename the schedule

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}B7C458E9-D207-4998-BAD0-3AFF0E6FA365ID of the schedule to update

Request Body

{
  "Name": "Unit Tests"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Name": "Unit Tests",
  "ProjectId": "42b9a01e-8a84-462c-adb9-3f96d3d7de52",
  "ProjectName": "Project XYZ",
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/configurations",
      "Rel": "ScheduleConfigurations"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test Schedule Import Configuration ( /api/automatedtestschedule/{scheduleId}/importconfiguration/{configId} )

Automated Test Schedule Import Configuration resource

This resource supports the following methods: DELETE, GET, PATCH, PUT

Methods

DELETE


Removes a configuration from an automated test schedule.

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if you do not have permission to remove the configuration from the automated test schedule.
404 - NotFoundReturned if schedule or configuration does not exist.

Example - DELETE

Remove an import configuration from an automated test schedule (Duette Schedule)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365Unique identifier of the schedule the import configuration belongs to.
{configId}62FF8D7C-9256-4C6B-B889-3600F675F5A7Unique identifier of the import configuration.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves a configuration for an automated test schedule.

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if you do not have permission to view the automated test schedule configuration.
404 - NotFoundReturned if schedule or configuration does not exist.

Example - GET

Retrieve a single import configuration associated with automated test schedule (Duette Schedule)

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365Unique identifier of the schedule the import configuration belongs to.
{configId}62FF8D7C-9256-4C6B-B889-3600F675F5A7Unique identifier of the import configuration.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SubType": "NUnit",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "SkipIfFilesUnchanged": true,
  "Description": "DefaultPath: N/A, XSLT File: N/A",
  "Enabled": true,
  "Expands": [
    "FieldValues",
    "Widgets",
    "ExecutionPackagePath",
    "ScriptPackagePath"
  ],
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/importconfiguration/62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Rel": "Schedule"
    }
  ]
}

Status Code

200 - OK

PATCH


Patches a configuration in an automated test schedule (currently only allows changing the 'Enabled' property).

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if you do not have permission to patch the automated test schedule the configuration belongs to.
404 - NotFoundReturned if schedule or configuration does not exist.

Example - PATCH

Disable an enabled import configuration

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365Unique identifier of the schedule the import configuration belongs to.
{configId}62FF8D7C-9256-4C6B-B889-3600F675F5A7Unique identifier of the import configuration.

Request Body

{
  "Enabled": false
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SubType": "NUnit",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "SkipIfFilesUnchanged": true,
  "Description": "DefaultPath: N/A, XSLT File: N/A",
  "Enabled": false,
  "Expands": [
    "FieldValues",
    "Widgets",
    "ExecutionPackagePath",
    "ScriptPackagePath"
  ],
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/importconfiguration/62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Rel": "Schedule"
    }
  ]
}

Status Code

200 - OK

PUT


Updates a configuration in an automated test schedule.

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if you do not have permission to update the automated test schedule the configuration belongs to.
404 - NotFoundReturned if schedule or configuration does not exist.

Example - PUT (using FieldValues)

Update (replace) the import configuration - this demonstrates passing in a full FieldValues object where you can specify additional options such as SubType, Default path etc.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365Unique identifier of the schedule the import configuration belongs to.
{configId}62FF8D7C-9256-4C6B-B889-3600F675F5A7Unique identifier of the import configuration.
$expandFieldValuesinclude FieldValues object in response

Request Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "FieldValues": {
    "DefaultPath": "c:\\testdata\\",
    "Type": "NUnit"
  },
  "SkipIfFilesUnchanged": true
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SubType": "NUnit",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "SkipIfFilesUnchanged": true,
  "Description": "DefaultPath: N/A, XSLT File: N/A",
  "Enabled": true,
  "Expands": [
    "Widgets",
    "ExecutionPackagePath",
    "ScriptPackagePath"
  ],
  "FieldValues": {
    "Type": "NUnit",
    "DefaultPath": null,
    "XsltFile": null
  },
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/importconfiguration/62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Rel": "Schedule"
    }
  ]
}

Status Code

200 - OK

Example - PUT (using in-line SubType)

Update (replace) the import configuration - this demonstrates supplying SubType in-line.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365Unique identifier of the schedule the import configuration belongs to.
{configId}62FF8D7C-9256-4C6B-B889-3600F675F5A7Unique identifier of the import configuration.

Request Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SubType": "NUnit",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "SkipIfFilesUnchanged": true
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SubType": "NUnit",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "SkipIfFilesUnchanged": true,
  "Description": "DefaultPath: N/A, XSLT File: N/A",
  "Enabled": true,
  "Expands": [
    "FieldValues",
    "Widgets",
    "ExecutionPackagePath",
    "ScriptPackagePath"
  ],
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/importconfiguration/62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Rel": "Schedule"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Test Schedule Import Configurations ( /api/automatedtestschedule/{id}/importconfigurations )

Automated Test Schedule Import Configurations (collection) resource

This resource supports the following methods: GET, POST

Methods

GET


Retrieves the list of automated test schedule configurations.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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
200 - OKReturned if request completed successfully.
403 - ForbiddenReturned if you do not have permission to view the automated test schedule the configurations belong to.
404 - NotFoundReturned if schedule does not exist.

Example - GET

Retrieve all import configurations belonging to an automated test schedule (Duette Schedule)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}B7C458E9-D207-4998-BAD0-3AFF0E6FA365Unique identifier of the automated test schedule

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Total": 1,
  "Items": [
    {
      "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Id": "62ff8d7c-9256-4c6b-b889-3600f675f5a7",
      "Name": "All NUnit Results",
      "Type": "UnitTest",
      "SubType": "NUnit",
      "SourcePath": "C:\\testdata\\{name}.xml",
      "NameTemplate": "{name}",
      "CombineResults": false,
      "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
      "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
      "MaximumNumberOfResultsRetained": 10,
      "SkipIfFilesUnchanged": true,
      "Description": "DefaultPath: N/A, XSLT File: N/A",
      "Enabled": true,
      "Expands": [
        "FieldValues",
        "Widgets",
        "ExecutionPackagePath",
        "ScriptPackagePath"
      ],
      "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/importconfiguration/62ff8d7c-9256-4c6b-b889-3600f675f5a7",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
          "Rel": "Schedule"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Adds a new configuration to the automated test schedule.

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
200 - OKReturned if request completed successfully.
400 - BadRequestReturned if schedule configuration has a different ScheduleId to the Id specified in the route.
403 - ForbiddenReturned if you do not have permission to add a new configuration to the automated test schedule.
404 - NotFoundReturned if schedule does not exist.

Example - POST (using in-line SubType)

Create a new import configuration for an automated test schedule (Duette Schedule) - this demonstrates supplying SubType in-line.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SubType": "NUnit",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "SkipIfFilesUnchanged": true
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SubType": "NUnit",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "SkipIfFilesUnchanged": true,
  "Description": "DefaultPath: N/A, XSLT File: N/A",
  "Enabled": true,
  "Expands": [
    "FieldValues",
    "Widgets",
    "ExecutionPackagePath",
    "ScriptPackagePath"
  ],
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/importconfiguration/62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Rel": "Schedule"
    }
  ]
}

Status Code

201 - Created

Example - POST (using FieldValues)

Create a new import configuration for an automated test schedule (Duette Schedule) - this demonstrates passing in a full FieldValues object where you can specify additional options such as SubType, Default path etc.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
$expandFieldValuesinclude FieldValues object in response

Request Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "FieldValues": {
    "DefaultPath": "c:\\testdata\\",
    "Type": "NUnit"
  },
  "SkipIfFilesUnchanged": true
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Name": "All NUnit Results",
  "Type": "UnitTest",
  "SubType": "NUnit",
  "SourcePath": "C:\\testdata\\{name}.xml",
  "NameTemplate": "{name}",
  "CombineResults": false,
  "ScriptPackageId": "05ec0839-3c87-41ce-9940-fd142563c28f",
  "ExecutionPackageId": "6ee31f73-b36a-4288-9ce9-23281054e365",
  "MaximumNumberOfResultsRetained": 10,
  "SkipIfFilesUnchanged": true,
  "Description": "DefaultPath: N/A, XSLT File: N/A",
  "Enabled": true,
  "Expands": [
    "Widgets",
    "ExecutionPackagePath",
    "ScriptPackagePath"
  ],
  "FieldValues": {
    "Type": "NUnit",
    "DefaultPath": null,
    "XsltFile": null
  },
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/importconfiguration/62ff8d7c-9256-4c6b-b889-3600f675f5a7",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Rel": "Schedule"
    }
  ]
}

Status Code

201 - Created

Resource: Automated Test Schedule Schedule Configuration ( /api/automatedtestschedule/{scheduleId}/schedule/{scheduleConfigId} )

Represents a single schedule associated with a synchronization configuration

This resource supports the following methods: DELETE, GET, PATCH, PUT

Methods

DELETE


Deletes a schedule.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to delete this resource.

Example - Delete Schedule

Example of deleting a schedule.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365The ID of the automated test schedule set (Duette Schedule).
{scheduleConfigId}BBD69B4E-4CFE-435D-8A5D-634A3CC11732The ID of the schedule configuration to remove.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves information about a schedule.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view this resource.

Example - Get Schedule

Example of retrieving a schedule.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365The ID of the automated test schedule set (Duette Schedule).
{scheduleConfigId}BBD69B4E-4CFE-435D-8A5D-634A3CC11732The ID of the schedule configuration.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Configuration": {
    "PeriodInMinutes": 15,
    "Type": "Periodic"
  },
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "bbd69b4e-4cfe-435d-8a5d-634a3cc11732",
  "Description": "Periodic (repeating every 15 minutes); Synchronizing from External System; Synchronize Updates",
  "Enabled": true,
  "IsRunning": false,
  "StatusMessage": "Synchronization Completed (Started At: 5/10/2012 12:36:52 p.m., Duration: 00:00:00.0810046)",
  "LastRun": "2012-10-04T23:36:00Z",
  "NextRun": "2012-10-04T23:51:00Z",
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/schedules/bbd69b4e-4cfe-435d-8a5d-634a3cc11732"
}

Status Code

200 - OK

PATCH


Patches an existing schedule (the Enabled status property only).

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to update this resource.

Example - Disable the Schedule

Example of using PATCH to disable the schedule. Note: Currently PATCH only supports changing the 'Enabled' status

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365The ID of the automated test schedule set (Duette Schedule).
{scheduleConfigId}BBD69B4E-4CFE-435D-8A5D-634A3CC11732The ID of the schedule configuration.

Request Body

{ "Enabled": false }

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Configuration": {
    "PeriodInMinutes": 15,
    "Type": "Periodic"
  },
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "bbd69b4e-4cfe-435d-8a5d-634a3cc11732",
  "Description": "Periodic (repeating every 15 minutes)",
  "Enabled": false,
  "IsRunning": false,
  "StatusMessage": "Import Completed (Started At: 5/10/2012 12:36:52 p.m., Duration: 00:00:00.0810046)",
  "LastRun": "2012-10-04T23:36:00Z",
  "NextRun": "2012-10-04T23:51:00Z",
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/schedules/bbd69b4e-4cfe-435d-8a5d-634a3cc11732"
}

Status Code

200 - OK

PUT


Update an existing schedule.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to update this resource.

Example - Update Schedule

An example of updating the schedule configuration.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}B7C458E9-D207-4998-BAD0-3AFF0E6FA365The ID of the automated test schedule set (Duette Schedule).
{scheduleConfigId}BBD69B4E-4CFE-435D-8A5D-634A3CC11732The ID of the schedule configuration.

Request Body

{
  "Configuration": {
    "PeriodInMinutes": 15,
    "Type": "Periodic"
  },
  "Enabled": true
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Configuration": {
    "PeriodInMinutes": 15,
    "Type": "Periodic"
  },
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "bbd69b4e-4cfe-435d-8a5d-634a3cc11732",
  "Description": "Periodic (repeating every 15 minutes)",
  "Enabled": true,
  "IsRunning": false,
  "StatusMessage": "Import Completed (Started At: 5/10/2012 12:36:52 p.m., Duration: 00:00:00.0810046)",
  "LastRun": "2012-10-04T23:36:00Z",
  "NextRun": "2012-10-04T23:51:00Z",
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/schedules/bbd69b4e-4cfe-435d-8a5d-634a3cc11732"
}

Status Code

200 - OK

Resource: Automated Test Schedule Schedule Configuration Run ( /api/automatedtestschedule/{scheduleId}/schedule/{scheduleConfigId}/run )

A resource you can POST to for initiating a run of a specific schedule configuration associated with an Automated Test Schedule (Duette Schedule).

This resource supports the following methods: POST

Methods

POST


Trigger the schedule to immediately start importing results.

Required Permissions

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 schedule was triggered.
403 - ForbiddenReturned if the user does not have permission to add a new schedule.

Example - Initiate import immediately for a schedule

Update the schedule configuration

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{scheduleId}91c059b3-f0d8-4507-9d02-b80aa3df50f2ID of the ExternalSystemLink representing the synchronizer the schedule belongs to
{scheduleConfigId}bbd69b4e-4cfe-435d-8a5d-634a3cc11732ID of the schedule

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

202 - Accepted

Resource: Automated Test Schedule Schedule Configurations ( /api/automatedtestschedule/{id}/schedules )

This is a collection resource for schedules associated with an automated tests schedule configuration set (Duette schedule).

This resource supports the following methods: GET, POST

Methods

GET


Retrieves information about an automated test schedule set's schedules.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view this resource.

Example - Get All Schedules for an Automated Test (Duette) schedule set

An Example of retrieving all schedules.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}B7C458E9-D207-4998-BAD0-3AFF0E6FA365The ID of the automated test schedule set (Duette Schedule) to retrieve schedules for.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Configuration": {
        "PeriodInMinutes": 15,
        "Type": "Periodic"
      },
      "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Id": "bbd69b4e-4cfe-435d-8a5d-634a3cc11732",
      "Description": "Periodic (repeating every 15 minutes)",
      "Enabled": true,
      "IsRunning": false,
      "StatusMessage": "Import Completed (Started At: 5/10/2012 12:36:52 p.m., Duration: 00:00:00.0810046)",
      "LastRun": "2012-10-04T23:36:00Z",
      "NextRun": "2012-10-04T23:51:00Z",
      "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/schedules/bbd69b4e-4cfe-435d-8a5d-634a3cc11732"
    },
    {
      "Configuration": {
        "Type": "AdHoc"
      },
      "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Id": "437246d4-c1ec-4da2-a4a7-2371847a1be1",
      "Description": "Ad-hoc",
      "Enabled": true,
      "IsRunning": false,
      "StatusMessage": "Idle",
      "LastRun": null,
      "NextRun": null,
      "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/schedules/437246d4-c1ec-4da2-a4a7-2371847a1be1"
    }
  ],
  "Self": "http://localhost/api/api/automatedtestschedule/91C059B3-F0D8-4507-9D02-B80AA3DF50F2/schedules"
}

Status Code

200 - OK

POST


Creates a new schedule for importing results.

Required Permissions

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
201 - CreatedReturned if the new schedule was created successfully.
403 - ForbiddenReturned if the user does not have permission to add a new schedule.

Example - Create a new Schedule

An Example of creating a new schedule for the automated test schedule set (Duette Schedule).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}B7C458E9-D207-4998-BAD0-3AFF0E6FA365The ID of the automated test schedule set (Duette Schedule) to add a schedule to.

Request Body

{
  "Configuration": {
    "Type": "AdHoc"
  },
  "Enabled": true
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/synchronizer/91C059B3-F0D8-4507-9D02-B80AA3DF50F2/schedule/BBD69B4E-4CFE-435D-8A5D-634A3CC11732

Response Body

{
  "Configuration": {
    "Type": "AdHoc"
  },
  "ScheduleId": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Id": "437246d4-c1ec-4da2-a4a7-2371847a1be1",
  "Description": "Ad-hoc",
  "Enabled": true,
  "IsRunning": false,
  "StatusMessage": "Idle",
  "LastRun": null,
  "NextRun": null,
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/schedules/437246d4-c1ec-4da2-a4a7-2371847a1be1"
}

Status Code

201 - Created

Resource: Automated Test Schedules ( /api/automatedtestschedules )

Automated Test Schedules (collection) resource

Root Relation: AutomatedTestSchedules

This resource supports the following methods: GET, POST

Methods

GET


Retrieves the list of automated test schedules.

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
200 - OKReturned if request completed successfully.

Example - GET (for all projects)

Retrieves a list of automated test schedules in application (all projects)

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Total": 1,
  "Items": [
    {
      "Id": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Name": "Unit Tests",
      "ProjectId": "42b9a01e-8a84-462c-adb9-3f96d3d7de52",
      "ProjectName": "Project XYZ",
      "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/configurations",
          "Rel": "ScheduleConfigurations"
        }
      ]
    },
    {
      "Id": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Name": "Import Selenium Tests",
      "ProjectId": "9e1fe662-c6c0-4dd6-8198-e630e4951f6d",
      "ProjectName": "Project ABC",
      "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/configurations",
          "Rel": "ScheduleConfigurations"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/automatedtestschedules"
}

Status Code

200 - OK

Example - GET (for project)

An example of retrieving a list of automated test schedules associated with a project.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
projectId42B9A01E-8A84-462C-ADB9-3F96D3D7DE52The ID of the project associated with the list of automated test schedules.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Total": 1,
  "Items": [
    {
      "Id": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Name": "Unit Tests",
      "ProjectId": "42b9a01e-8a84-462c-adb9-3f96d3d7de52",
      "ProjectName": "Project XYZ",
      "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/configurations",
          "Rel": "ScheduleConfigurations"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/automatedtestschedules?projectId=42B9A01E-8A84-462C-ADB9-3F96D3D7DE52"
}

Status Code

200 - OK

POST


Creates a new automated test schedule.

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
201 - CreatedReturned if request completed successfully.
403 - ForbiddenIf you do not have permission to create a schedule for the select project, or project was invalid.

Example - POST

An example of creating a new test schedule. Note: After creating the schedule you must populate the import and import schedule configurations before the schedule will be usable.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Body

{
  "Name": "Unit Tests",
  "ProjectId": "42b9a01e-8a84-462c-adb9-3f96d3d7de52"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Name": "Unit Tests",
  "ProjectId": "42b9a01e-8a84-462c-adb9-3f96d3d7de52",
  "ProjectName": "Project XYZ",
  "Self": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtestschedule/b7c458e9-d207-4998-bad0-3aff0e6fa365/configurations",
      "Rel": "ScheduleConfigurations"
    }
  ]
}

Status Code

201 - Created

Resource: Automated Test Type ( /api/automatedtesttype/{name} )

Automated test type resource

This resource supports the following methods: GET

Methods

GET


Retrieves automated test type by its name.

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
200 - OKReturned if request completed successfully.
404 - NotFoundReturned if the automated test type does not exist.

Example - Example - Get automated test type

Example of retrieving an automated test type by its name.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{name}UnitTestThe name of the automated test type to retrieve

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Name": "UnitTest",
  "FriendlyName": "Unit Test Results",
  "Types": [
    {
      "Name": "NUnit",
      "FriendlyName": "NUnit"
    },
    {
      "Name": "JUnit",
      "FriendlyName": "JUnit"
    }
  ],
  "Self": "http://localhost/api/automatedtesttype/unittest"
}

Status Code

200 - OK

Resource: Automated Test Types ( /api/automatedtesttypes )

Automated Test Types (collection) resource

Root Relation: AutomatedTestTypes

This resource supports the following methods: GET

Methods

GET


Retrieves the list of automated test types

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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
200 - OKReturned if request completed successfully.
404 - NotFoundReturned if the automated test type does not exist.

Example - Example - Get all automated test type

Example of getting all automated test types

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Name": "UnitTest",
      "FriendlyName": "Unit Test Results",
      "Types": [
        {
          "Name": "NUnit",
          "FriendlyName": "NUnit"
        },
        {
          "Name": "JUnit",
          "FriendlyName": "JUnit"
        }
      ],
      "Self": "http://localhost/api/automatedtesttype/unittest"
    },
    {
      "Name": "Selenium",
      "FriendlyName": "Selenium",
      "Types": [],
      "Self": "http://localhost/api/automatedtesttype/selenium"
    }
  ]
}

Status Code

200 - OK

Resource: Automated Tests ( /api/automatedtests )

Automated tests (collection) resource

Root Relation: AutomatedTests

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of automated tests that are visible.

This method supports the TQL query parameters tql, $top, $take and $inlinecount. See TQL Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete request (normally due to a validation failure or the necessary permissions to complete the request were not met).

Example - Get all automated test

Retrieve all automated tests

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "Id": "dff56a5f-40fa-41d5-8bc8-33c3d0014368",
      "Type": "UnitTest",
      "Name": "JUnit Results",
      "CreatedAt": "2012-01-02T15:05:06Z",
      "LastUpdatedAt": "2012-02-02T15:05:06Z",
      "CreatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "CreatedBy": "joeb",
      "LastUpdatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "LastUpdatedBy": "joeb",
      "AssignedToId": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "AssignedTo": "joeb",
      "PackageId": "68f38eb7-9882-41b8-9749-712c43dc3f51",
      "ProjectId": "4f0d1bc3-3247-4ad0-b753-aaa538d8c523",
      "ProjectName": "Test Project",
      "PackageName": "Script Library",
      "OrderNumber": 1,
      "Expands": [
        "Assignments",
        "Configuration"
      ],
      "Self": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/assignments",
          "Rel": "Assignments"
        }
      ]
    },
    {
      "Id": "08348cb0-1313-4721-bfcb-b9e02a0cd5bc",
      "Type": "Selenium",
      "Name": "Login Tests",
      "CreatedAt": "2012-03-02T15:05:06Z",
      "LastUpdatedAt": "2012-04-02T16:05:06Z",
      "CreatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "CreatedBy": "joeb",
      "LastUpdatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "LastUpdatedBy": "joeb",
      "AssignedToId": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "AssignedTo": "joeb",
      "PackageId": "68f38eb7-9882-41b8-9749-712c43dc3f51",
      "ProjectId": "4f0d1bc3-3247-4ad0-b753-aaa538d8c523",
      "ProjectName": "Test Project",
      "PackageName": "Script Library",
      "OrderNumber": 2,
      "Expands": [
        "Assignments",
        "Configuration"
      ],
      "Self": "http://localhost/api/automatedtest/08348cb0-1313-4721-bfcb-b9e02a0cd5bc",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtest/08348cb0-1313-4721-bfcb-b9e02a0cd5bc/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/08348cb0-1313-4721-bfcb-b9e02a0cd5bc/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/08348cb0-1313-4721-bfcb-b9e02a0cd5bc/assignments",
          "Rel": "Assignments"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Example - Get automated tests (with TQL query)

Retrieve automated tests matching TQL query

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
tqlType = UnitTest

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 1,
  "Items": [
    {
      "Id": "dff56a5f-40fa-41d5-8bc8-33c3d0014368",
      "Type": "UnitTest",
      "Name": "JUnit Results",
      "CreatedAt": "2012-01-02T15:05:06Z",
      "LastUpdatedAt": "2012-02-02T15:05:06Z",
      "CreatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "CreatedBy": "joeb",
      "LastUpdatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "LastUpdatedBy": "joeb",
      "AssignedToId": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
      "AssignedTo": "joeb",
      "PackageId": "68f38eb7-9882-41b8-9749-712c43dc3f51",
      "ProjectId": "4f0d1bc3-3247-4ad0-b753-aaa538d8c523",
      "ProjectName": "Test Project",
      "PackageName": "Script Library",
      "OrderNumber": 1,
      "Expands": [
        "Assignments",
        "Configuration"
      ],
      "Self": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368",
      "Links": [
        {
          "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/automatedtest/dff56a5f-40fa-41d5-8bc8-33c3d0014368/assignments",
          "Rel": "Assignments"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Creates a new automated test

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete request (normally due to a validation failure or the necessary permissions to complete the request were not met.).

Example - Create a new automated test

Create automated test

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}DFF56A5F-40FA-41D5-8BC8-33C3D0014368The unique identifier of automated test to return.

Request Body

{
  "Type": "UnitTest",
  "Name": "Cycle 2 JUnit Results",
  "AssignedToId": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "PackageId": "68f38eb7-9882-41b8-9749-712c43dc3f51",
  "OrderNumber": 1,
  "Configuration": {
    "Type": "JUnit"
  }
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/automatedtest/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Type": "UnitTest",
  "Name": "Cycle 2 JUnit Results",
  "CreatedAt": "2012-01-02T15:05:06Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "CreatedBy": "joeb",
  "LastUpdatedById": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "LastUpdatedBy": "joeb",
  "AssignedToId": "f10c226f-1778-4038-b0d4-2eae86bd5a9e",
  "AssignedTo": "joeb",
  "PackageId": "68f38eb7-9882-41b8-9749-712c43dc3f51",
  "ProjectId": "4f0d1bc3-3247-4ad0-b753-aaa538d8c523",
  "ProjectName": "Test Project",
  "PackageName": "Script Library",
  "OrderNumber": 1,
  "Expands": [
    "Assignments",
    "Configuration"
  ],
  "Self": "http://localhost/api/automatedtest/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/automatedtest/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/automatedtest/4bb709c2-e0e7-4af3-9f60-a045016a9610/assignments",
      "Rel": "Assignments"
    }
  ]
}

Status Code

201 - Created

Resource: Background Task ( /api/backgroundtask/{id} )

The Background Task resource allows you to retrieve the details of a currently executed or completed task. This includes information related to the progress (% completed) of the task.

This resource supports the following methods: GET

Methods

GET


Retrieves the status of a running or completed job. Note that after some time completed jobs will be flushed. At this point, this method will return a '404 Not Found' response.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if no job was found with the sepcified identifier.

Example - In Progress Task

Example of retrieving the progress status for a task that is running in the background.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}reindex-7bdba522-590a-4df4-b409-a2939851241bThe Unique identifier of the job (string).

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 5,
  "StartedAt": "2011-12-31T11:00:00Z",
  "ProgressInPercent": 0.5,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Reticulating Splines",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

200 - OK

Example - Completed Task

Example of retrieving the progress for a task that has finished.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}reindex-7bdba522-590a-4df4-b409-a2939851241bUnique identifier of the job (string)

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Complete": true,
  "TotalElements": 10,
  "ProcessedElements": 10,
  "StartedAt": "2011-12-31T12:00:00Z",
  "FinishedAt": "2011-12-31T12:10:14Z",
  "ProgressInPercent": 1.0,
  "Id": "reindex-7bdba522-590a-4df4-b409-a2939851241b",
  "Message": "Task Completed",
  "Self": "http://localhost/api/backgroundtask/reindex-7bdba522-590a-4df4-b409-a2939851241b"
}

Status Code

200 - OK

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

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

Resource: Custom Field ( /api/customfield/{name} )

Custom field resource

This resource supports the following methods: GET

Methods

GET


Retrieves a custom field by its identifier.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the custom field type does not exist.

Example - GET

Example of retrieving a custom field by its name.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{name}IsRegressionThe name of the custom field to retrieve.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4b4329a0-44a3-4e3c-a527-6973bb2b063b",
  "Name": "IsRegression",
  "CustomFieldTypeName": "Checkbox",
  "Label": "Is Regression?",
  "Description": null,
  "Required": false,
  "Entities": [
    "TestScript",
    "Requirement",
    "Incident"
  ],
  "Scopes": [
    {
      "Type": "Project",
      "Id": "d17289f6-8f43-4074-88d0-3841f9830b19",
      "Name": "Test Project"
    }
  ],
  "Expands": [
    "Configuration",
    "Options",
    "Type"
  ],
  "Self": "http://localhost/api/customfield/IsRegression",
  "Links": [
    {
      "Href": "http://localhost/api/customfieldtype/checkbox",
      "Rel": "CustomFieldType"
    }
  ]
}

Status Code

200 - OK

Resource: Custom Field Type ( /api/customfieldtype/{name} )

Custom field type resource

This resource supports the following methods: GET

Methods

GET


Retrieves a custom field type by its name.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the custom field type does not exist.

Example - Get custom field type

Example of fetching all custom field types.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{name}TextThe name of the custom field type to retrieve.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Name": "Text",
      "DisplayName": "Text",
      "Self": "http://localhost/api/customfieldtype/text"
    }
  ]
}

Status Code

200 - OK

Resource: Custom Field Types ( /api/customfieldtypes )

Custom field types (collection) resource

Root Relation: CustomFieldTypes

This resource supports the following methods: GET

Methods

GET


Retrieves the list of custom field types.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the custom field type does not exist.

Example - Get all custom field types

Example of fetching all custom field types.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Name": "Text",
      "DisplayName": "Text",
      "Self": "http://localhost/api/customfieldtype/text"
    },
    {
      "Name": "ComboBox",
      "DisplayName": "Combo Box",
      "Self": "http://localhost/api/customfieldtype/combobox"
    },
    {
      "Name": "Checkbox",
      "DisplayName": "Checkbox",
      "Self": "http://localhost/api/customfieldtype/checkbox"
    }
  ]
}

Status Code

200 - OK

Example - Get custom field types using OData filter

Example of fetching subset of custom field types using OData filter.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterName eq 'Text'Fetch custom field type with name 'Text'

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Name": "Text",
      "DisplayName": "Text",
      "Self": "http://localhost/api/customfieldtype/text"
    }
  ]
}

Status Code

200 - OK

Resource: Custom Fields ( /api/customfields )

Custom fields (collection) resource

Root Relation: CustomFields

This resource supports the following methods: GET

Methods

GET


Retrieves all custom fields.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the custom field type does not exist.

Example - Get all custom fields

An Example of fetching all custom fields.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "4b4329a0-44a3-4e3c-a527-6973bb2b063b",
      "Name": "IsRegression",
      "CustomFieldTypeName": "Checkbox",
      "Label": "Is Regression?",
      "Description": null,
      "Required": false,
      "Entities": [
        "TestScript",
        "Requirement",
        "Incident"
      ],
      "Scopes": [
        {
          "Type": "Project",
          "Id": "d17289f6-8f43-4074-88d0-3841f9830b19",
          "Name": "Test Project"
        }
      ],
      "Expands": [
        "Configuration",
        "Options",
        "Type"
      ],
      "Self": "http://localhost/api/customfield/IsRegression",
      "Links": [
        {
          "Href": "http://localhost/api/customfieldtype/checkbox",
          "Rel": "CustomFieldType"
        }
      ]
    },
    {
      "Id": "8b385cac-fcbf-4d27-83d0-132e121e8ea1",
      "Name": "Severity",
      "CustomFieldTypeName": "ComboBox",
      "Label": "Severity",
      "Description": null,
      "Required": true,
      "Entities": [
        "Incident"
      ],
      "Scopes": [
        {
          "Type": "Organisation",
          "Id": "3d0d2ebf-d9c4-40bb-ab8e-85d63dab1f8a",
          "Name": "Testing Intl"
        }
      ],
      "Expands": [
        "Configuration",
        "Options",
        "Type"
      ],
      "Self": "http://localhost/api/customfield/Severity",
      "Links": [
        {
          "Href": "http://localhost/api/customfieldtype/combobox",
          "Rel": "CustomFieldType"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Example - Get custom fields using OData filter

An Example of fetching subset of custom fields using OData filter and expansion for options.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterCustomFieldTypeName eq 'ComboBox'Fetch all custom fields of type combo box.
$expandOptionsExpands the options for any matching field.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "8b385cac-fcbf-4d27-83d0-132e121e8ea1",
      "Name": "Severity",
      "CustomFieldTypeName": "ComboBox",
      "Label": "Severity",
      "Description": null,
      "Required": true,
      "Entities": [
        "Incident"
      ],
      "Scopes": [
        {
          "Type": "Organisation",
          "Id": "3d0d2ebf-d9c4-40bb-ab8e-85d63dab1f8a",
          "Name": "Testing Intl"
        }
      ],
      "Expands": [
        "Configuration",
        "Type"
      ],
      "Options": [
        {
          "Identifier": "05ec42ae-2713-4d51-9306-3226a2446712",
          "Text": "Low"
        },
        {
          "Identifier": "05ec42ae-2713-4d51-9306-3226a2446712",
          "Text": "Medium"
        },
        {
          "Identifier": "05ec42ae-2713-4d51-9306-3226a2446712",
          "Text": "High"
        }
      ],
      "Self": "http://localhost/api/customfield/Severity",
      "Links": [
        {
          "Href": "http://localhost/api/customfieldtype/combobox",
          "Rel": "CustomFieldType"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Resource: Execution Package ( /api/executionpackage/{id} )

Execution Package resource

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Deletes an execution package by its unique identifier.

Required Permissions

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
200 - OKReturned if execution package was deleted successfully.
403 - ForbiddenReturned if execution package can not be deleted (normally because required permission have not been met or the package has children but you did not pass the deleteChildren parameter.).
404 - NotFoundReturned if execution package was not found.

Example - Delete empty package

Example of deleting a package.

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of package to delete.

Status Code

200 - OK

Example - Delete package with children

Example of deleting a package with children.

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of package to delete.
deleteChildrentrueWill delete a package and all its children.

Status Code

200 - OK

Example - Delete package with children (without deleteChildren parameter)

Example of deleting a non-empty package without deleteChildren=true.

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of package to delete.

Response Body

{
  "Message": "The package is not empty."
}

Status Code

403 - Forbidden

GET


Retrieves an execution package by its unique identifier.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if execution package was not found.

Example - GET

Example of retrieving execution package by unique identifier.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of package to retrieve.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "ParentId": "cc91ec0b-a9f2-44fe-bf86-97ecb98cecc6",
  "Name": "New Package Name",
  "Stereotype": null,
  "OrderNumber": 1,
  "Expands": [
    "Children",
    "Parent",
    "Project"
  ],
  "Self": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610/children",
      "Rel": "Children"
    },
    {
      "Href": "http://localhost/api/executionpackage/cc91ec0b-a9f2-44fe-bf86-97ecb98cecc6",
      "Rel": "Parent"
    }
  ]
}

Status Code

200 - OK

PUT


Update an execution package.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to create execution packages in the target project.
404 - NotFoundReturned if the package does not exist.

Example - PUT (update package name)

Updating a package name.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of package to delete.

Request Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "New Package Name"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "ProjectId": "944aa658-8067-42cf-a6a6-ce71535a73bc",
  "Name": "New Package Name",
  "Stereotype": null,
  "OrderNumber": 1,
  "Expands": [
    "Children",
    "Parent",
    "Project"
  ],
  "Self": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610/children",
      "Rel": "Children"
    },
    {
      "Href": "http://localhost/api/project/944aa658-8067-42cf-a6a6-ce71535a73bc",
      "Rel": "Project"
    }
  ]
}

Status Code

200 - OK

Example - PUT (move package to new parent)

Updating package to have a different parent.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of package to delete.

Request Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "ParentId": "cc91ec0b-a9f2-44fe-bf86-97ecb98cecc6"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "ParentId": "cc91ec0b-a9f2-44fe-bf86-97ecb98cecc6",
  "Name": "New Package Name",
  "Stereotype": null,
  "OrderNumber": 1,
  "Expands": [
    "Children",
    "Parent",
    "Project"
  ],
  "Self": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610/children",
      "Rel": "Children"
    },
    {
      "Href": "http://localhost/api/executionpackage/cc91ec0b-a9f2-44fe-bf86-97ecb98cecc6",
      "Rel": "Parent"
    }
  ]
}

Status Code

200 - OK

Example - PUT (update multiple details)

Updating package name, stereotype, order and parent.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of the package to delete.

Request Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "New Package Name",
  "Stereotype": "Plan",
  "OrderNumber": 2,
  "ParentId": "cc91ec0b-a9f2-44fe-bf86-97ecb98cecc6"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "ParentId": "cc91ec0b-a9f2-44fe-bf86-97ecb98cecc6",
  "Name": "New Package Name",
  "Stereotype": "Plan",
  "OrderNumber": 2,
  "Expands": [
    "Children",
    "Parent",
    "Project"
  ],
  "Self": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610/children",
      "Rel": "Children"
    },
    {
      "Href": "http://localhost/api/executionpackage/cc91ec0b-a9f2-44fe-bf86-97ecb98cecc6",
      "Rel": "Parent"
    }
  ]
}

Status Code

200 - OK

Resource: Execution Package Children ( /api/executionpackage/{id}/children )

Execution Package resource

This resource supports the following methods: GET

Methods

GET


Retrieves the children of the execution package.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to create execution packages in the target project.
404 - NotFoundReturned if the package does not exist.

Example - GET

Example of retrieving all child packages for package.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of the parent package.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "2d33ee96-7634-4363-891f-d90a15709bb9",
      "ParentId": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Name": "Cycle 1",
      "Stereotype": "Plan",
      "OrderNumber": 1,
      "Expands": [
        "Children",
        "Parent",
        "Project"
      ],
      "Self": "http://localhost/api/executionpackage/2d33ee96-7634-4363-891f-d90a15709bb9",
      "Links": [
        {
          "Href": "http://localhost/api/executionpackage/2d33ee96-7634-4363-891f-d90a15709bb9/children",
          "Rel": "Children"
        },
        {
          "Href": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610",
          "Rel": "Parent"
        }
      ]
    },
    {
      "Id": "ed07f8a1-3ffa-4f25-bc28-0dae55650205",
      "ParentId": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Name": "Cycle 2",
      "Stereotype": "Plan",
      "OrderNumber": 2,
      "Expands": [
        "Children",
        "Parent",
        "Project"
      ],
      "Self": "http://localhost/api/executionpackage/ed07f8a1-3ffa-4f25-bc28-0dae55650205",
      "Links": [
        {
          "Href": "http://localhost/api/executionpackage/ed07f8a1-3ffa-4f25-bc28-0dae55650205/children",
          "Rel": "Children"
        },
        {
          "Href": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610",
          "Rel": "Parent"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Resource: Execution Packages ( /api/executionpackages )

Execution Packages collection resource

Root Relation: ExecutionPackages

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of execution packages that are visible.

This method supports the TQL query parameters tql, $top, $take and $inlinecount. See TQL Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - GET (filtered by TQL Query)

Retrieves all packages matching a TQL query.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
tqlName ~ 'Report'The TQL query to execute.
$top5Maximum number of results to return (defaults to 25).
$skip0Number of results to skip before return the $top number of results matching the query.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 1,
  "Items": [
    {
      "Id": "d009c056-6025-4a5e-a3b9-fc0fa8cf1f2e",
      "ProjectId": "944aa658-8067-42cf-a6a6-ce71535a73bc",
      "Name": "Reports",
      "Stereotype": "Package",
      "OrderNumber": 0,
      "Expands": [
        "Children",
        "Parent",
        "Project"
      ],
      "Self": "http://localhost/api/executionpackage/d009c056-6025-4a5e-a3b9-fc0fa8cf1f2e",
      "Links": [
        {
          "Href": "http://localhost/api/executionpackage/d009c056-6025-4a5e-a3b9-fc0fa8cf1f2e/children",
          "Rel": "Children"
        },
        {
          "Href": "http://localhost/api/project/944aa658-8067-42cf-a6a6-ce71535a73bc",
          "Rel": "Project"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/executionpackages?tql=Name~'Report'&$top=5&$skip=0"
}

Status Code

200 - OK

Example - GET (no TQL query)

Retrieves all packages, across all projects.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "Id": "d009c056-6025-4a5e-a3b9-fc0fa8cf1f2e",
      "ProjectId": "944aa658-8067-42cf-a6a6-ce71535a73bc",
      "Name": "Reports",
      "Stereotype": "Package",
      "OrderNumber": 0,
      "Expands": [
        "Children",
        "Parent",
        "Project"
      ],
      "Self": "http://localhost/api/executionpackage/d009c056-6025-4a5e-a3b9-fc0fa8cf1f2e",
      "Links": [
        {
          "Href": "http://localhost/api/executionpackage/d009c056-6025-4a5e-a3b9-fc0fa8cf1f2e/children",
          "Rel": "Children"
        },
        {
          "Href": "http://localhost/api/project/944aa658-8067-42cf-a6a6-ce71535a73bc",
          "Rel": "Project"
        }
      ]
    },
    {
      "Id": "7c8ffe51-c584-41d6-8739-8dbd56d5770f",
      "ProjectId": "944aa658-8067-42cf-a6a6-ce71535a73bc",
      "Name": "Data Import",
      "Stereotype": "Package",
      "OrderNumber": 0,
      "Expands": [
        "Children",
        "Parent",
        "Project"
      ],
      "Self": "http://localhost/api/executionpackage/7c8ffe51-c584-41d6-8739-8dbd56d5770f",
      "Links": [
        {
          "Href": "http://localhost/api/executionpackage/7c8ffe51-c584-41d6-8739-8dbd56d5770f/children",
          "Rel": "Children"
        },
        {
          "Href": "http://localhost/api/project/944aa658-8067-42cf-a6a6-ce71535a73bc",
          "Rel": "Project"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/executionpackages"
}

Status Code

200 - OK

POST


Create a new execution package.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to create execution packages in the target project.

Example - POST (top-level package)

Create a new package (at root of project).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "Name": "New Package",
  "ProjectId": "4545fe95-e9c2-40e9-8f4a-3f000d14526f"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "ProjectId": "944aa658-8067-42cf-a6a6-ce71535a73bc",
  "Name": "New Package",
  "Stereotype": "Package",
  "OrderNumber": 0,
  "Expands": [
    "Children",
    "Parent",
    "Project"
  ],
  "Self": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610/children",
      "Rel": "Children"
    },
    {
      "Href": "http://localhost/api/project/944aa658-8067-42cf-a6a6-ce71535a73bc",
      "Rel": "Project"
    }
  ]
}

Status Code

201 - Created

Example - POST (child of existing package)

Create a new package (as child of existing package).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "Name": "New Child Package",
  "ParentId": "9bfeb244-06a6-4440-b6b6-a8bcc0847673"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "ParentId": "9bfeb244-06a6-4440-b6b6-a8bcc0847673",
  "Name": "New Child Package",
  "Stereotype": "Package",
  "OrderNumber": 0,
  "Expands": [
    "Children",
    "Parent",
    "Project"
  ],
  "Self": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/executionpackage/4bb709c2-e0e7-4af3-9f60-a045016a9610/children",
      "Rel": "Children"
    },
    {
      "Href": "http://localhost/api/executionpackage/9bfeb244-06a6-4440-b6b6-a8bcc0847673",
      "Rel": "Parent"
    }
  ]
}

Status Code

201 - Created

Resource: Export File ( /api/exportfile/{filename} )

Used to retrieve the contents of an exported file.

This resource supports the following methods: GET

Methods

GET


Retrieves the contents of an exported file.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the file does not exist.

Example - Get export file contents

Example of retrieving the contents of an exported file.

Request Headers

KeyValueDescription
Accepttext/csv

Request Parameters

KeyValueDescription
{filename}export-Entities-2012-07-03-115806pm.csvThe filename to download.

Response Headers

KeyValueDescription
Content-Typetext/csv

Status Code

200 - OK

Resource: External Source Metadata ( /api/externalsourcemetadata )

Allows the retrieval of an external source's metadata. Metadata provides identifying information and additional field metadata which can be used when creating a new link by POSTing to the /api/externalsystemlink resource.

The metadata for external sources have an associated end - the 'Source' end is for entities within Enterprise Tester (e.g. requirement, test script and incident).

The 'Destination' end is for entities in external systems (e.g. Issues in Jira, test cases in Enterprise Architect, User stories in rally etc.).

To create a suitable link between a 'Source' and 'Destination' end, the 'Destination' end must be compatible with the 'Source' end - the metadata returned from these resources allows you to identify compatible source and destination ends via the property 'CompatibleWithSourceKeys'.

This resource supports the following methods: GET

Methods

GET


Retrieves an external resource identified by its attributes.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Retrieve an external source's metadata identified by end and key

An example of retrieving an external source's metadata identified by end and key. This is a common approach for retrieving a source for the 'Source' (ET) end.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
endSourceThe end the source belongs to
keyRequirementThe key of the source

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "End": "Source",
  "Name": "Requirements",
  "Id": null,
  "Key": "Requirement",
  "CompatibleWithSourceKeys": null,
  "Expands": [
    "Widgets",
    "InitialFieldValues"
  ],
  "Self": "http://localhost/api/externalsourcemetadata?key=Requirement&end=Source"
}

Status Code

200 - OK

Example - Retrieve an external source's metadata identified by end, key and external system ID

An example of retrieving an external source's metadata identified by end, key and external system.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
endDestinationThe end the source belongs to.
keySynchronizationThe key of the source.
id0a1e8d7a-0078-4941-92e7-a17a00ed142fThe unique identifier for the the external system.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "End": "Destination",
  "Name": "TFS2010 - TFS",
  "Id": "0a1e8d7a-0078-4941-92e7-a17a00ed142f",
  "Key": "Synchronization",
  "CompatibleWithSourceKeys": [
    "Requirement"
  ],
  "Expands": [
    "Widgets",
    "InitialFieldValues"
  ],
  "Self": "http://localhost/api/externalsourcemetadata?id=0a1e8d7a-0078-4941-92e7-a17a00ed142f&key=Synchronization&end=Destination"
}

Status Code

200 - OK

Resource: External Sources Metadata ( /api/externalsourcesmetadata )

Allows the retrieval of an external sources metadata. Metadata provides identifying information and additional field metadata which can be used when creating a new link by POSTing to the /api/externalsystemlink resource.

The metadata for external sources have an associated end - the 'Source' end is for entities within Enterprise Tester (e.g. requirement, test script and incident).

The 'Destination' end is for entities in external systems (e.g. Issues in Jira, test cases in Enterprise Architect, User stories in rally etc.).

To create a suitable link between a 'Source' and 'Destination' end, the 'Destination' end must be compatible with the 'Source' end - the metadata returned from these resources allows you to identify compatible source and destination ends via the property 'CompatibleWithSourceKeys'.

Root Relation: ExternalSourcesMetadata

This resource supports the following methods: GET

Methods

GET


Retrieves all (or a subset) of external sources.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Retrieve all external sources metadata

An example of retrieving all external sources metadata.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "End": "Source",
      "Name": "Requirements",
      "Id": null,
      "Key": "Requirement",
      "CompatibleWithSourceKeys": null,
      "Expands": [
        "Widgets",
        "InitialFieldValues"
      ],
      "Self": "http://localhost/api/externalsourcemetadata?key=Requirement&end=Source"
    },
    {
      "End": "Destination",
      "Name": "TFS2010 - TFS",
      "Id": "0a1e8d7a-0078-4941-92e7-a17a00ed142f",
      "Key": "Synchronization",
      "CompatibleWithSourceKeys": [
        "Requirement"
      ],
      "Expands": [
        "Widgets",
        "InitialFieldValues"
      ],
      "Self": "http://localhost/api/externalsourcemetadata?id=0a1e8d7a-0078-4941-92e7-a17a00ed142f&key=Synchronization&end=Destination"
    }
  ],
  "Self": "http://localhost/EnterpriseTester/api/externalsourcesmetadata"
}

Status Code

200 - OK

Example - Retrieve filtered list of external sources metadata

Retrieve all external sources metadata filtered by compatibleWithKey and end (The example shows retrieving 'Destination' ends compatible for requirement synchronization).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
compatibleWithKeyRequirementThe filter to apply to the 'CompatibleWithSourceKeys' value.
endDestinationThe end to filter external sources by (valid values are 'Source' and 'Destination').

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "End": "Destination",
      "Name": "TFS2010 - TFS",
      "Id": "0a1e8d7a-0078-4941-92e7-a17a00ed142f",
      "Key": "Synchronization",
      "CompatibleWithSourceKeys": [
        "Requirement"
      ],
      "Expands": [
        "Widgets",
        "InitialFieldValues"
      ],
      "Self": "http://localhost/api/externalsourcemetadata?id=0a1e8d7a-0078-4941-92e7-a17a00ed142f&key=Synchronization&end=Destination"
    }
  ],
  "Self": "http://localhost/EnterpriseTester/api/externalsourcesmetadata?end=Destination&compatibleWithKey=Requirement"
}

Status Code

200 - OK

Example - Retrieve external sources metadata for the 'Source' end which are compatible with a destination end Id

Retrieve an external source's metadata identified by end and compatibleWithId - this is a common approach for retrieving a set of sources for the 'Source' end which are known to be compatible with a desintation end (external system).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
endSourceThe end the source belongs to.
compatibleWithIdAB743B14-4F7F-49EB-9215-B99236D18C43ID of the destination end the sources must be compatible with.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "End": "Source",
  "Name": "Requirements",
  "Id": null,
  "Key": "Requirement",
  "CompatibleWithSourceKeys": null,
  "Expands": [
    "Widgets",
    "InitialFieldValues"
  ],
  "Self": "http://localhost/api/externalsourcemetadata?key=Requirement&end=Source"
}

Status Code

200 - OK

Resource: External System ( /api/externalsystem/{id} )

Allows the retrieval of the details for a single external system (Defect Tracker, Enterprise Architect connection etc.).

This resource supports the following methods: DELETE, GET, PATCH, PUT

Methods

DELETE


Delete the external system.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if external system does not exist.

Example - Delete an external system and retain references.

Delete an external system and retain references (previously synchronized entities will remain unchanged after deleting the system).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}A01FC7ED-3492-4792-9A0B-E2B52FA10913Unique identifier of the external system to delete.
keepReferencestrueKeep references but delete the external system (this is the default value for this parameter and can be omitted).

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

Example - Delete an external system and remove references.

Delete an external system and remove references (previously synchronized entities will no longer show as being synchronized to the external system).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}A01FC7ED-3492-4792-9A0B-E2B52FA10913Unique identifier of the external system to delete.
keepReferencesfalseDo not retain references (previously synchronized entities will have all references for this system removed).

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves a single external system by its identifier.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if external system does not exist.

Example - Get External System

Example of fetching an external system by ID

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a01fc7ed-3492-4792-9a0b-e2b52fa10913

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "OrganisationId": null,
  "Name": "TFS",
  "Type": "TFS2010",
  "ConnectionType": "TFS2010",
  "ConnectionString": "http://tfs.mycompany.com:8080/tfs/Projects",
  "Enabled": true,
  "QualifiedName": null,
  "TypeDescription": null,
  "NumberOfLinks": 0,
  "Categories": [],
  "UserName": "remote_tfs",
  "HasPassword": true,
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "Self": "http://localhost/api/externalsystem/a01fc7ed-3492-4792-9a0b-e2b52fa10913"
}

Status Code

200 - OK

Example - Get External System with configuration problems

Example of fetching an external system by ID which has configuration problems.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a01fc7ed-3492-4792-9a0b-e2b52fa10913

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "OrganisationId": null,
  "Name": "TFS",
  "Type": "TFS2010",
  "ConnectionType": "TFS2010",
  "ConnectionString": "http://tfs.mycompany.com:8080/tfs/Projects",
  "Enabled": true,
  "QualifiedName": null,
  "TypeDescription": null,
  "NumberOfLinks": 0,
  "Categories": [],
  "UserName": null,
  "HasPassword": false,
  "ConfigurationComplete": false,
  "ConfigurationProblems": [
    "UserName is not configured",
    "Password is not configured"
  ],
  "Self": "http://localhost/api/externalsystem/a01fc7ed-3492-4792-9a0b-e2b52fa10913"
}

Status Code

200 - OK

PATCH


Updates the enabled state of the external system to enabled or disabled.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if external system does not exist.

Example - Enable an external system

Enabling a disabled external system (will cause validation of external system configuration).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}744904d6-9612-4e87-a718-7b5d80c0060dUnique identifier of the external system to update.

Request Body

{ "Enabled": true }

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "744904d6-9612-4e87-a718-7b5d80c0060d",
  "OrganisationId": null,
  "Name": "Jira",
  "Type": "Jira",
  "ConnectionType": "Jira",
  "ConnectionString": "http://mycompany.com:8090/",
  "Enabled": true,
  "QualifiedName": null,
  "TypeDescription": null,
  "NumberOfLinks": 0,
  "Categories": [],
  "UserName": "remote",
  "HasPassword": true,
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d"
}

Status Code

200 - OK

PUT


Update the external system.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if external system does not exist.

Example - Update external system

An example of updating an external system with full configuration supplied in field values (Note: we set 'Enabled' true, which will cause the configuration to be validated).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}744904d6-9612-4e87-a718-7b5d80c0060dUnique identifier of the external system to update.
$expandFieldValuesInclude field values in response as well.

Request Body

{
  "Type": "Jira",
  "Name": "Jira",
  "Enabled": true,
  "FieldValues": {
    "Url": "http://mycompany.com:8090/",
    "UserName": "remote",
    "Password": "password",
    "IgnoreInvalidRemoteCertificates": false
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "744904d6-9612-4e87-a718-7b5d80c0060d",
  "OrganisationId": null,
  "Name": "Jira",
  "Type": "Jira",
  "ConnectionType": "Jira",
  "ConnectionString": "http://mycompany.com:8090/",
  "Enabled": true,
  "QualifiedName": null,
  "TypeDescription": null,
  "NumberOfLinks": 0,
  "Categories": [],
  "UserName": "remote",
  "HasPassword": true,
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "FieldValues": {
    "Url": "http://mycompany.com:8090/",
    "UserName": "remote",
    "Password": "password",
    "IgnoreInvalidRemoteCertificates": false
  },
  "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d"
}

Status Code

200 - OK

Resource: External System Link ( /api/externalsystemlink/{id} )

Allows the retrieval of details for a single external system link (Incident, Requirement, UseCase link etc.).

This resource supports the following methods: DELETE, GET, PATCH

Methods

DELETE


Deletes the external system link and optionally removes all associated references and events.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if external system link does not exist.

Example - Delete External System Link (and retain external system references)

An example of deleting an external system and retaining all the external references and events (previously synchronized entities will remain unchanged after deleting the link).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a01fc7ed-3492-4792-9a0b-e2b52fa10913
keepReferencestrueKeep references but delete the link (this is the default value for this parameter and can be omitted).

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

Example - Delete External System Link (and remove external system references)

An example of deleting external system and removing all external system references and events.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a01fc7ed-3492-4792-9a0b-e2b52fa10913
keepReferencesfalseRemove all references and events associated with this link.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves a single external system link by its identifier.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have the necessary permissions to view this external system link.
404 - NotFoundReturned if external system link does not exist.

Example - Get External System Link

An example of retrieving an external system link by its identifier.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a01fc7ed-3492-4792-9a0b-e2b52fa10913

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
  "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
  "ProjectName": null,
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Type": "Incident",
  "TypeForDisplay": null,
  "ExternalSystemName": "Jira PROD",
  "ExternalSystemImplementationType": "Jira",
  "ExternalSystemConnectionType": null,
  "Name": "Project X",
  "Enabled": false,
  "LastSynchronizedAt": "2012-01-01T14:04:07Z",
  "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
  "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "AutoSelect": "NotApplicable",
  "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Links": [
    {
      "Title": "Configuration Editor",
      "Href": "http://localhost/api",
      "Rel": "Edit"
    }
  ]
}

Status Code

200 - OK

PATCH


Updates the enabled state of the external system link to enabled or disabled.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if external system link does not exist.

Example - Enable External System Link

An example of changing the enabled state of a link by its ID.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a01fc7ed-3492-4792-9a0b-e2b52fa10913

Request Body

{ "Enabled": true }

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
  "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
  "ProjectName": null,
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Type": "Incident",
  "TypeForDisplay": null,
  "ExternalSystemName": "Jira PROD",
  "ExternalSystemImplementationType": "Jira",
  "ExternalSystemConnectionType": null,
  "Name": "Project X",
  "Enabled": true,
  "LastSynchronizedAt": "2012-01-01T14:04:07Z",
  "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
  "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "AutoSelect": "NotApplicable",
  "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Links": [
    {
      "Title": "Configuration Editor",
      "Href": "http://localhost/api",
      "Rel": "Edit"
    }
  ]
}

Status Code

200 - OK

Resource: External System Link Copy ( /api/externalsystemlink/{linkId}/copy )

This is the resource which when POST'd to will create a copy of an existing external system link, targeting a new internal/remote project.

This resource supports the following methods: POST

Methods

POST


Create a a copy of an external systems link.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the request was completed successfully.

Example - Create a new external system link, by copying the configuration from an existing link.

Create a new External System Link between a project in ET and a project in Jira, synchronizing requirements, and copying the configuration from an existing link.

The ID of the existing external system link to copy the configuration from is identified in the 'CopyFromLinkId' parameter.

The ID of the project in ET is specified in the 'ProjectId' parameter of the Source FieldVaues object.

The ID of the project in Jira is specified in the 'ProjectId' parameter of the Destination FieldValues object.

Note: To determine the required FieldValues you can supply the '$expand=InitialFieldValues' query parameter when retrieving the list of External Sources from /api/externalsources, to include examples of what FieldValues are expected.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{linkId}b45599d1-d2b4-48d2-ad7e-db8d2882b7d9Identifier of the external system link to copy configuration from.

Request Body

{
  "Source": {
    "Key": "Requirement",
    "Id": null,
    "FieldValues": {
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281"
    }
  },
  "Destination": {
    "Key": "Synchronization",
    "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "FieldValues": {
      "ProjectId": "12345"
    }
  },
  "Name": "Project X",
  "CopyFromLinkId": "b45599d1-d2b4-48d2-ad7e-db8d2882b7d9"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
  "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
  "ProjectName": null,
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Type": "Requirement",
  "TypeForDisplay": null,
  "ExternalSystemName": "Rally",
  "ExternalSystemImplementationType": "Rally",
  "ExternalSystemConnectionType": null,
  "Name": "Project X Requirements",
  "Enabled": true,
  "LastSynchronizedAt": "2012-01-01T14:04:07Z",
  "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
  "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "AutoSelect": "NotApplicable",
  "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Links": [
    {
      "Title": "Configuration Editor",
      "Href": "http://localhost/api",
      "Rel": "Edit"
    }
  ]
}

Status Code

201 - Created

Resource: External System Link Field Values ( /api/externalsystemlink/{linkId}/field/{fieldName} )

Allows retrieval the allowable values for a field associated with an external system link.

This resource supports the following methods: GET

Methods

GET


Retrieves all options for a field belonging to an external system link.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you dont not have permission to retrieve field values for this link.
404 - NotFoundReturned if the link does not exist.

Example - Get all options for a field

An example of retrieving all options for a field belonging to an external system link.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{linkId}DF463CBF-32C9-4295-8B6C-55AAE7B640B9
{fieldName}Priority

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 3,
  "Items": [
    {
      "Identifier": "1",
      "Text": "High"
    },
    {
      "Identifier": "2",
      "Text": "Medium"
    },
    {
      "Identifier": "3",
      "Text": "Low"
    }
  ]
}

Status Code

200 - OK

Example - Get all options for field by matching a partial name query

An example of retrieving options for a field belonging to an external system link by matching a partial name query.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{linkId}DF463CBF-32C9-4295-8B6C-55AAE7B640B9
{fieldName}Priority
queryH

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 1,
  "Items": [
    {
      "Identifier": "1",
      "Text": "High"
    }
  ]
}

Status Code

200 - OK

Resource: External System Link Ticket ( /api/externalsystemlink/{externalSystemLinkId}/ticket/{ticketId} )

Allows the retrieval of a single project ticket.

This resource supports the following methods: GET

Methods

GET


Retrieves a single ticket by its unique identifier.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if external system does not exist.

Example - Get ticket

Example of Retrieving a ticket by its Id and the external system link its associated with.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{ticketId}18759
{externalSystemLinkId}c63e805c-e5d3-4919-9d10-a0a500e0754a

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Key": "TST-4629",
  "Summary": "Test windows title clips text on bottom",
  "Url": "https://mycompany.atlassian.net/browse/TST-4629",
  "Id": "18759",
  "Type": "Bug",
  "ExternalSystemId": "c63e805c-e5d3-4919-9d10-a0a500e0754a",
  "ExternalSystemName": "testing",
  "IncidentId": null,
  "Status": "Open",
  "InternalKey": null,
  "Self": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a/ticket/18759",
  "Links": [
    {
      "Href": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a/ticket/18759/link",
      "Rel": "StartCreateIncident"
    },
    {
      "Href": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a",
      "Rel": "ExternalSystemLink"
    }
  ]
}

Status Code

200 - OK

Resource: External System Link Ticket Link ( /api/externalsystemlink/{externalSystemLinkId}/ticket/{ticketId}/link )

Allows the creation of a new incident in ET that is synchronized to a ticket in an external system (JIRA, TFS or Rally).

This resource supports the following methods: POST

Methods

POST


Creates a background task for creating an incident from an external ticket. Note: this task completes asynchronously and may take some time to complete.

Required Permissions

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, or the parameters are invalid.

Example - Start background task to create new incident linked to ticket

An example of creating a new incident synchronized with a ticket. Note: When the task completes, retrieving the progress of the task will include a link to the Incident that was created and an additional value, 'IncidentId'.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{ticketId}16841ID of the ticket to link to. In cases of systems such as JIRA, this is the internal identifier, not the 'Key' for the ticket (issue).
{externalSystemLinkId}c63e805c-e5d3-4919-9d10-a0a500e0754aThis is the unique identifier of the external system link in ET.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Complete": false,
  "TotalElements": 0,
  "ProcessedElements": 0,
  "StartedAt": "2012-08-06T11:28:45Z",
  "ProgressInPercent": 0.0,
  "Id": "ticketlinking_cba3035a-bf63-4006-89b1-b291aaac0460",
  "Message": null,
  "Self": "http://localhost/api/backgroundtask/ticketlinking_cba3035a-bf63-4006-89b1-b291aaac0460"
}

Status Code

202 - Accepted

Example - Create new incident linked to ticket (when task completed immediately)

This example shows the progress response of linking once completed, including the additional details of the Incident that was created.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{ticketId}16841ID of the ticket to link to. In cases of systems such as JIRA, this is the internal identifier, not the 'Key' for the ticket (issue).
{externalSystemLinkId}9b01796c-a9ae-40cb-a6ad-a802346c0c33This is the unique identifier of the external system link in ET.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Complete": true,
  "StartedAt": "2012-08-06T11:39:45Z",
  "FinishedAt": "2012-08-06T11:39:53Z",
  "ProgressInPercent": 1.0,
  "Id": "ticketlinking_9b01796c-a9ae-40cb-a6ad-a802346c0c33",
  "Message": "Completed",
  "IncidentId": "029b2c43-38be-4c94-b547-a0a50185fb9e",
  "Self": "http://localhost/api/backgroundtask/ticketlinking_9b01796c-a9ae-40cb-a6ad-a802346c0c33",
  "Links": [
    {
      "Href": "http://localhost/api/incident/029b2c43-38be-4c94-b547-a0a50185fb9e",
      "Rel": "Incident"
    }
  ]
}

Status Code

202 - Accepted

Resource: External System Links ( /api/externalsystemlinks )

This is the collection resource for external system links. This allows the search and retrieval of a list of all or a subset of external system links (Defect Trackers, Enterprise Architect connections etc.).

Root Relation: ExternalSystemLinks

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of external system links.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Get all external system links

An example of retrieving all external system links.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
      "ProjectName": null,
      "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Type": "Incident",
      "TypeForDisplay": null,
      "ExternalSystemName": "Jira PROD",
      "ExternalSystemImplementationType": "Jira",
      "ExternalSystemConnectionType": null,
      "Name": "Project X",
      "Enabled": false,
      "LastSynchronizedAt": "2012-01-01T14:04:07Z",
      "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
      "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "AutoSelect": "NotApplicable",
      "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Links": [
        {
          "Title": "Configuration Editor",
          "Href": "http://localhost/api",
          "Rel": "Edit"
        }
      ]
    },
    {
      "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
      "ProjectName": null,
      "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Type": "Requirement",
      "TypeForDisplay": null,
      "ExternalSystemName": "Jira PROD",
      "ExternalSystemImplementationType": "Jira",
      "ExternalSystemConnectionType": null,
      "Name": "Project X",
      "Enabled": false,
      "LastSynchronizedAt": "2012-01-01T14:04:07Z",
      "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
      "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "AutoSelect": "NotApplicable",
      "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Links": [
        {
          "Title": "Configuration Editor",
          "Href": "http://localhost/api",
          "Rel": "Edit"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Example - Get all external system links filtered by type

An example of retrieving a set of external system links by type and project Id, by using the ODATA $filter query parameter.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterType eq 'Incident' and ProjectId eq guid'3AFBE0DD-55CA-419E-B75D-D21C821D7281'The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Type%20eq%20'Incident'%20and%20ProjectId%20eq%20guid'3AFBE0DD-55CA-419E-B75D-D21C821D7281'

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 1,
  "Items": [
    {
      "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
      "ProjectName": null,
      "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Type": "Incident",
      "TypeForDisplay": null,
      "ExternalSystemName": "Jira PROD",
      "ExternalSystemImplementationType": "Jira",
      "ExternalSystemConnectionType": null,
      "Name": "Project X",
      "Enabled": false,
      "LastSynchronizedAt": "2012-01-01T14:04:07Z",
      "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
      "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "AutoSelect": "NotApplicable",
      "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Links": [
        {
          "Title": "Configuration Editor",
          "Href": "http://localhost/api",
          "Rel": "Edit"
        }
      ]
    }
  ],
  "Self": "http://localhost/Enterprise/ExternalSystemLinks?$filter=Type eq 'Incident' and ProjectId eq guid'3AFBE0DD-55CA-419E-B75D-D21C821D7281'"
}

Status Code

200 - OK

POST


Create a new external systems link.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the request was completed successfully.

Example - Create a new external system link

Create a new External System Link between a project in ET and a project in Jira, synchronizing requirements.

The ID of the project in ET is specified in the 'ProjectId' parameter of the Source FieldVaues object.

The ID of the project in Jira is specified in the 'ProjectId' parameter of the Destination FieldValues object.

Note: To determine the required FieldValues you can supply the '$expand=InitialFieldValues' query parameter when retrieving the list of External Sources from /api/externalsources, to include examples of what FieldValues are expected.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Body

{
  "Source": {
    "Key": "Requirement",
    "Id": null,
    "FieldValues": {
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281"
    }
  },
  "Destination": {
    "Key": "Synchronization",
    "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "FieldValues": {
      "ProjectId": "12345"
    }
  },
  "Name": "Project X"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
  "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
  "ProjectName": null,
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Type": "Requirement",
  "TypeForDisplay": null,
  "ExternalSystemName": "Rally",
  "ExternalSystemImplementationType": "Rally",
  "ExternalSystemConnectionType": null,
  "Name": "Project X Requirements",
  "Enabled": true,
  "LastSynchronizedAt": "2012-01-01T14:04:07Z",
  "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
  "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "AutoSelect": "NotApplicable",
  "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Links": [
    {
      "Title": "Configuration Editor",
      "Href": "http://localhost/api",
      "Rel": "Edit"
    }
  ]
}

Status Code

201 - Created

Example - Create a new external system link which is disabled

Create a new External System Link between a project in ET and a project in Jira, synchronizing requirements, and create it with the 'Enabled' state set to false.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Body

{
  "Source": {
    "Key": "Requirement",
    "Id": null,
    "FieldValues": {
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281"
    }
  },
  "Destination": {
    "Key": "Synchronization",
    "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "FieldValues": {
      "ProjectId": "12345"
    }
  },
  "Name": "Project X",
  "Enabled": false
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
  "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
  "ProjectName": null,
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Type": "Requirement",
  "TypeForDisplay": null,
  "ExternalSystemName": "Rally",
  "ExternalSystemImplementationType": "Rally",
  "ExternalSystemConnectionType": null,
  "Name": "Project X Requirements",
  "Enabled": false,
  "LastSynchronizedAt": "2012-01-01T14:04:07Z",
  "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
  "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "AutoSelect": "NotApplicable",
  "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Links": [
    {
      "Title": "Configuration Editor",
      "Href": "http://localhost/api",
      "Rel": "Edit"
    }
  ]
}

Status Code

201 - Created

Resource: External System Links Search ( /api/project/{projectId}/searchlinks )

Allows the searching of all external systems for a project by partial match.

Root Relation: ProjectExternalSystemLinksSearch

This resource supports the following methods: GET, POST

Methods

GET


Searches for externa links by partial name match

Required Permissions

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
200 - OKReturned if the search request was able to be satisfied.

Example - Search for project external system links

An example of searching for project external system links.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
queryjoThe partial external system link name
$skip20Number of items to skip (start result number)
$top10Number of search results to return
$inlinecountallpagesInclude or supress inline counts

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 20,
  "Top": 10,
  "Total": 1,
  "Items": [
    {
      "ExternalSystemId": "0df3c581-599d-41da-95a6-2e79ff9676dc",
      "ProjectId": "b8992d43-6e24-4b75-93b8-25168c7e64af",
      "ProjectName": "Project X",
      "Id": "3464e9da-f1b7-49aa-87db-7e1eebfd17a5",
      "Type": "Incident",
      "TypeForDisplay": "Incident",
      "ExternalSystemName": "Jira PROD",
      "ExternalSystemImplementationType": "JIRA5",
      "ExternalSystemConnectionType": "Incident",
      "Name": "Project X Incidents",
      "Enabled": true,
      "LastSynchronizedAt": "2013-01-01T14:04:05Z",
      "LastDestinationToSourceSynchronizationAt": null,
      "LastSourceToDestinationSynchronizationAt": null,
      "DefectTrackerProjectId": "123",
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "AutoSelect": "NotApplicable",
      "Expands": [
        "Configuration",
        "ExternalSystem"
      ],
      "Self": "http://localhost/api/externalsystemlink/3464e9da-f1b7-49aa-87db-7e1eebfd17a5",
      "Links": [
        {
          "Title": "Configuration Editor",
          "Href": "http://localhost/api",
          "Rel": "Edit"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/project/B8992D43-6E24-4B75-93B8-25168C7E64AF/searchlinks?query=proj&$skip=20&$top=10&$inlinecount=allpages",
  "Links": [
    {
      "Href": "http://localhost/api/project/B8992D43-6E24-4B75-93B8-25168C7E64AF/searchlinks?query=proj&$skip=10&$top=10&$inlinecount=allpages",
      "Rel": "prev"
    },
    {
      "Href": "http://localhost/api/project/B8992D43-6E24-4B75-93B8-25168C7E64AF/searchlinks?query=proj&$skip=0&$top=10&$inlinecount=allpages",
      "Rel": "first"
    }
  ]
}

Status Code

200 - OK

POST


Searches for external links by partial name match (using POST to allow large existing value queries).

Required Permissions

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
200 - OKReturned if the search request was able to be satisfied.

Example - Search for project external system links

An example of searching for project external system links.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
queryjoThe partial external system link name
$skip20Number of items to skip (start result number)
$top10Number of search results to return
$inlinecountallpagesInclude or supress inline counts

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 20,
  "Top": 10,
  "Total": 1,
  "Items": [
    {
      "ExternalSystemId": "0df3c581-599d-41da-95a6-2e79ff9676dc",
      "ProjectId": "b8992d43-6e24-4b75-93b8-25168c7e64af",
      "ProjectName": "Project X",
      "Id": "3464e9da-f1b7-49aa-87db-7e1eebfd17a5",
      "Type": "Incident",
      "TypeForDisplay": "Incident",
      "ExternalSystemName": "Jira PROD",
      "ExternalSystemImplementationType": "JIRA5",
      "ExternalSystemConnectionType": "Incident",
      "Name": "Project X Incidents",
      "Enabled": true,
      "LastSynchronizedAt": "2013-01-01T14:04:05Z",
      "LastDestinationToSourceSynchronizationAt": null,
      "LastSourceToDestinationSynchronizationAt": null,
      "DefectTrackerProjectId": "123",
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "AutoSelect": "NotApplicable",
      "Expands": [
        "Configuration",
        "ExternalSystem"
      ],
      "Self": "http://localhost/api/externalsystemlink/3464e9da-f1b7-49aa-87db-7e1eebfd17a5",
      "Links": [
        {
          "Title": "Configuration Editor",
          "Href": "http://localhost/api",
          "Rel": "Edit"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/project/B8992D43-6E24-4B75-93B8-25168C7E64AF/searchlinks?$skip=20&$top=10&$inlinecount=allpages",
  "Links": [
    {
      "Href": "http://localhost/api/project/B8992D43-6E24-4B75-93B8-25168C7E64AF/searchlinks?$skip=10&$top=10&$inlinecount=allpages",
      "Rel": "prev"
    },
    {
      "Href": "http://localhost/api/project/B8992D43-6E24-4B75-93B8-25168C7E64AF/searchlinks?$skip=0&$top=10&$inlinecount=allpages",
      "Rel": "first"
    }
  ]
}

Status Code

200 - OK

Resource: External System Type ( /api/externalsystemtype/{id} )

Allows the retrieval of a single external system type.

This resource supports the following methods: GET

Methods

GET


Retrieves a single external system type.

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
200 - OKReturned if the request was completed successfully.

Example - Get a single external system type

An example of retrieving a single external system type.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}JiraThe ID of the external system type.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "Jira",
  "Name": "Jira",
  "Categories": [
    "DefectTracker"
  ],
  "Self": "http://localhost/api/externalsystemtype/Jira"
}

Status Code

200 - OK

Resource: External System Types ( /api/externalsystemtypes )

This is the collection resource which allows the search and retrieval of external system types.

Root Relation: ExternalSystemTypes

This resource supports the following methods: GET

Methods

GET


Retrieves all (or a subset) of external system types.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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
200 - OKReturned if the request was completed successfully.

Example - GET

Retrieve all external system types.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 3,
  "Items": [
    {
      "Id": "Jira",
      "Name": "Jira",
      "Categories": [
        "DefectTracker"
      ],
      "Self": "http://localhost/api/externalsystemtype/Jira"
    },
    {
      "Id": "TFS2010",
      "Name": "TFS 2010",
      "Categories": [
        "DefectTracker"
      ],
      "Self": "http://localhost/api/externalsystemtype/TFS2010"
    },
    {
      "Id": "EnterpriseArchitect",
      "Name": "Enterprise Architect",
      "Categories": [
        "CaseModelingTool"
      ],
      "Self": "http://localhost/api/externalsystemtype/EnterpriseArchitect"
    }
  ],
  "Self": "http://localhost/api/api/externalsystemtypes"
}

Status Code

200 - OK

Resource: External Systems ( /api/externalsystems )

This is a collection resource which allows the search and retrieval of all or a subset of external systems (Defect Trackers, Enterprise Architect connections etc.).

Root Relation: ExternalSystems

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of external systems.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Get all external systems

An example of retrieving all external systems.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "Id": "744904d6-9612-4e87-a718-7b5d80c0060d",
      "OrganisationId": null,
      "Name": "Jira",
      "Type": "Jira",
      "ConnectionType": "Jira",
      "ConnectionString": "http://mycompany.com:8090/",
      "Enabled": true,
      "QualifiedName": null,
      "TypeDescription": null,
      "NumberOfLinks": 0,
      "Categories": [],
      "UserName": "remote",
      "HasPassword": true,
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d"
    },
    {
      "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "OrganisationId": null,
      "Name": "TFS",
      "Type": "TFS2010",
      "ConnectionType": "TFS2010",
      "ConnectionString": "http://tfs.mycompany.com:8080/tfs/Projects",
      "Enabled": true,
      "QualifiedName": null,
      "TypeDescription": null,
      "NumberOfLinks": 0,
      "Categories": [],
      "UserName": "remote_tfs",
      "HasPassword": true,
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "Self": "http://localhost/api/externalsystem/a01fc7ed-3492-4792-9a0b-e2b52fa10913"
    }
  ],
  "Self": "http://localhost/ExternalSystems"
}

Status Code

200 - OK

Example - Get external systems filtered by type

An example of retrieving a set of external systems by type using the ODATA $filter query parameter.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterType eq 'Jira'The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Type%20eq%20'Jira'.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 1,
  "Items": [
    {
      "Id": "744904d6-9612-4e87-a718-7b5d80c0060d",
      "OrganisationId": null,
      "Name": "Jira",
      "Type": "Jira",
      "ConnectionType": "Jira",
      "ConnectionString": "http://mycompany.com:8090/",
      "Enabled": true,
      "QualifiedName": null,
      "TypeDescription": null,
      "NumberOfLinks": 0,
      "Categories": [],
      "UserName": "remote",
      "HasPassword": true,
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d"
    }
  ],
  "Self": "http://localhost/ExternalSystems?$filter=Type eq 'Jira'"
}

Status Code

200 - OK

POST


Create a new external system.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the request was completed successfully.

Example - Create new external system

An example of creating a new external system (without any additional field values).

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Body

{
  "Type": "Jira",
  "Name": "Jira"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/externalsystem/744904D6-9612-4E87-A718-7B5D80C0060D
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "744904d6-9612-4e87-a718-7b5d80c0060d",
  "OrganisationId": null,
  "Name": "Jira",
  "Type": "Jira",
  "ConnectionType": "Jira",
  "ConnectionString": "http://mycompany.com:8090/",
  "Enabled": true,
  "QualifiedName": null,
  "TypeDescription": null,
  "NumberOfLinks": 0,
  "Categories": [],
  "UserName": "remote",
  "HasPassword": true,
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d"
}

Status Code

201 - Created

Example - Create new external system (with field values)

An example of creating a new external system with full configuration supplied in field values.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
$expandFieldValuesInclude field values in response.

Request Body

{
  "Type": "Jira",
  "Name": "Jira",
  "FieldValues": {
    "Url": "http://mycompany.com:8090/",
    "UserName": "remote",
    "Password": "password",
    "IgnoreInvalidRemoteCertificates": false
  }
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/externalsystem/744904D6-9612-4E87-A718-7B5D80C0060D
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "744904d6-9612-4e87-a718-7b5d80c0060d",
  "OrganisationId": null,
  "Name": "Jira",
  "Type": "Jira",
  "ConnectionType": "Jira",
  "ConnectionString": "http://mycompany.com:8090/",
  "Enabled": true,
  "QualifiedName": null,
  "TypeDescription": null,
  "NumberOfLinks": 0,
  "Categories": [],
  "UserName": "remote",
  "HasPassword": true,
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "FieldValues": {
    "Url": "http://mycompany.com:8090/",
    "UserName": "remote",
    "Password": "password",
    "IgnoreInvalidRemoteCertificates": false
  },
  "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d"
}

Status Code

201 - Created

Resource: External System's Links ( /api/externalsystem/{systemId}/links )

A collection resource which allows the search and retrieval of external system links for a specific external system (Defect Trackers and Enterprise Architect connections).

This resource supports the following methods: GET

Methods

GET


Retrieves all (or a subset) external system links for a specific external system.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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
200 - OKReturned if the request was completed successfully.

Example - Get all external system links for a specific external system

An example of fetching all external system links

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{systemId}b5ee119f-bc44-4b3c-befe-919f2fe3f4f7The unique identifier for the external system.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
    "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
    "ProjectName": null,
    "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "Type": "Incident",
    "TypeForDisplay": null,
    "ExternalSystemName": "Jira PROD",
    "ExternalSystemImplementationType": "Jira",
    "ExternalSystemConnectionType": null,
    "Name": "Project X",
    "Enabled": false,
    "LastSynchronizedAt": "2012-01-01T14:04:07Z",
    "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
    "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
    "ConfigurationComplete": true,
    "ConfigurationProblems": [],
    "AutoSelect": "NotApplicable",
    "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "Links": [
      {
        "Title": "Configuration Editor",
        "Href": "http://localhost/api",
        "Rel": "Edit"
      }
    ]
  },
  {
    "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
    "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
    "ProjectName": null,
    "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "Type": "Requirement",
    "TypeForDisplay": null,
    "ExternalSystemName": "Rally",
    "ExternalSystemImplementationType": "Rally",
    "ExternalSystemConnectionType": null,
    "Name": "Project X Requirements",
    "Enabled": false,
    "LastSynchronizedAt": "2012-01-01T14:04:07Z",
    "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
    "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
    "ConfigurationComplete": true,
    "ConfigurationProblems": [],
    "AutoSelect": "NotApplicable",
    "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "Links": [
      {
        "Title": "Configuration Editor",
        "Href": "http://localhost/api",
        "Rel": "Edit"
      }
    ]
  }
]

Status Code

200 - OK

Example - Get all external system links for a specific external system filtered by type and project Id

An example of retrieving a set of external system links by type and project Id using the ODATA $filter query parameter.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{systemId}b5ee119f-bc44-4b3c-befe-919f2fe3f4f7The unique identifier for the external system.
$filterType eq 'Incident' and ProjectId eq guid'3AFBE0DD-55CA-419E-B75D-D21C821D7281'The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Type%20eq%20'Incident'%20and%20ProjectId%20eq%20guid'3AFBE0DD-55CA-419E-B75D-D21C821D7281'

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
    "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
    "ProjectName": null,
    "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "Type": "Incident",
    "TypeForDisplay": null,
    "ExternalSystemName": "Jira PROD",
    "ExternalSystemImplementationType": "Jira",
    "ExternalSystemConnectionType": null,
    "Name": "Project X",
    "Enabled": false,
    "LastSynchronizedAt": "2012-01-01T14:04:07Z",
    "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
    "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
    "ConfigurationComplete": true,
    "ConfigurationProblems": [],
    "AutoSelect": "NotApplicable",
    "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "Links": [
      {
        "Title": "Configuration Editor",
        "Href": "http://localhost/api",
        "Rel": "Edit"
      }
    ]
  }
]

Status Code

200 - OK

Resource: Grid Widget Data ( /api/gridwidget/{widgetType}/data/{dataName} )

Allows the retrieval of data for a grid widget.

This resource supports the following methods: POST

Methods

POST


Retrieves the data set for a grid widget.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if widget type was invalid.

Example - POST

Retrieve a set of data (by name) for a type of grid widget. Note: this is a POST rather than a GET request, because a large amount of contextual state must be passed in for this operation to complete.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{widgetType}RunStatusesGroupedByFieldForAutomatedRunsType of widget to return data from.
{dataName}resultsThe name of the data set to retrieve (data may be retrieved for displaying on the widget, or for populating additional metadata required for configuring the widget).

Request Body

{
  "IndexName": "Run",
  "AllowableTypes": [
    "AutomatedTestRun",
    "ScriptRun",
    "AgileRun"
  ],
  "BaseQuery": "AssignmentID = 2d8d6b25-0203-4595-9903-1325bcd85948",
  "ProjectId": "cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133",
  "PackageId": "df3097c2-0777-4156-9186-d321e9611481",
  "PackageType": "ExecutionPackage",
  "Query": "ORDER BY CreatedAt DESC",
  "Selections": [
    {
      "Id": "482c3531-1781-42ae-b084-7369964e674a",
      "Type": "AutomatedTestRun"
    },
    {
      "Id": "281850fd-cf28-484c-b88a-e4ff43b49e27",
      "Type": "AgileRun"
    }
  ],
  "TimeZone": "America/New_York",
  "Parameters": {
    "groupingType": "Field",
    "groupingField": "RunNumber"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Data": {
    "Results": [
      {
        "Key": "1",
        "InProgress": 0,
        "Undetermined": 0,
        "Errors": 0,
        "Failed": 167,
        "NotRun": 0,
        "Passed": 2588,
        "Skipped": 3,
        "Warnings": 0,
        "Blocked": 0
      }
    ]
  }
}

Status Code

0 - 0

Resource: Grid Widget State ( /api/gridwidgethost/{hostId}/project/{projectId}/position/{position} )

Allows retrieval of state information for a grid widget at a specified position within a widget host for the combination of current user and a specific project.

This resource supports the following methods: GET, PUT

Methods

GET


Retrieves the states of a widget at a specified position associated with a widget host for the current user and selected project.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if a position was not specified.
404 - NotFoundReturned if project or position does not exist.

Example - GET

Retrieve state of widget at specific position.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{hostId}automated_test_run_summaryID of the host for the set of grid widgets.
{projectId}cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133Unique ID of project the grid widgets are being displayed for.
{position}rightThe position of the widget within the grid widget host (current valid values are 'left' and 'right').

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Position": "right",
  "WidgetType": "RunStatusesGroupedByFieldForAutomatedRuns",
  "Data": {
    "groupingType": "Field",
    "groupingField": "RunNumber"
  },
  "Self": "http://localhost/api/gridwidgethost/automated_test_run_summary/project/cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133/position/right"
}

Status Code

200 - OK

PUT


Sets the state of a widget at a specified position associated with a widget host for the current user and selected project.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if a position was not specified.
404 - NotFoundReturned if widget type was invalid.

Example - PUT

Update state of widget at specific position.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{hostId}automated_test_run_summaryID of the host for the set of grid widgets.
{projectId}cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133Unique ID of project the grid widgets are being displayed for.
{position}rightThe position of the widget within the grid widget host (current valid values are 'left' and 'right').

Request Body

{
  "Position": null,
  "WidgetType": "RunStatusesGroupedByFieldForAutomatedRuns",
  "Data": {
    "groupingType": "Field",
    "groupingField": "RunNumber"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Position": "right",
  "WidgetType": "RunStatusesGroupedByFieldForAutomatedRuns",
  "Data": {
    "groupingType": "Field",
    "groupingField": "RunNumber"
  },
  "Self": "http://localhost/api/gridwidgethost/automated_test_run_summary/project/cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133/position/right"
}

Status Code

200 - OK

Resource: Grid Widget States ( /api/gridwidgethost/{hostId}/project/{projectId}/positions )

Grid widget states allow the retrieval of state information for all widgets associated with a Widget host ID.

This resource supports the following methods: GET

Methods

GET


Retrieves the states of all widgets associated with a widget host for the current user and selected project.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if project does not exist.

Example - GET

Retrieves the states of all widgets associated with a widget host.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{hostId}automated_test_run_summaryID of the host for the set of grid widgets.
{projectId}cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133Unique ID of project the grid widgets are being displayed for.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "HostId": "automated_test_run_summary",
  "Positions": {
    "left": {
      "Position": "left",
      "WidgetType": "RunStatusOverTime",
      "Data": {
        "selections": [
          "ScriptRun",
          "AgileRun"
        ]
      },
      "Self": "http://localhost/api/gridwidgethost/automated_test_run_summary/project/cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133/position/left"
    },
    "right": {
      "Position": "right",
      "WidgetType": "RunStatusesGroupedByFieldForAutomatedRuns",
      "Data": {
        "groupingType": "Field",
        "groupingField": "RunNumber"
      },
      "Self": "http://localhost/api/gridwidgethost/automated_test_run_summary/project/cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133/position/right"
    }
  },
  "Self": "http://localhost/api/gridwidgethost/automated_test_run_summary/project/cdd1a0cf-2cd1-4f9a-8513-a9a2fc74d133/positions"
}

Status Code

200 - OK

Resource: Group ( /api/group/{id} )

Allows the retrieval of details for an individual group.

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Deletes an existing group

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if request could not be completed.
404 - NotFoundReturned if group does not exists.

Example - Delete Group

Example of deleting a group.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}9e1ee34b-f96f-4005-9f7a-1457df86256d

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves a single group by ID.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if user does not exists.

Example - Get Group

Example of fetching a group

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}9e1ee34b-f96f-4005-9f7a-1457df86256d

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
  "Name": "QA",
  "Description": "QA Team (Testers + Test Managers)",
  "Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
  "Links": [
    {
      "Title": "Members",
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
      "Rel": "Users"
    },
    {
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
      "Rel": "GlobalPermissions"
    },
    {
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
      "Rel": "ProjectPermissions"
    }
  ]
}

Status Code

200 - OK

PUT


Updates an existing group

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if request contained invalid data or would cause a conflict with an existing group record.
404 - NotFoundReturned if group does not exists.

Example - Update Group

Example of updating group.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}9e1ee34b-f96f-4005-9f7a-1457df86256d

Request Body

{
  "Id": null,
  "Name": "QA",
  "Description": "QA Team (Testers + Test Managers)"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
  "Name": "QA",
  "Description": "QA Team (Testers + Test Managers)",
  "Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
  "Links": [
    {
      "Title": "Members",
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
      "Rel": "Users"
    },
    {
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
      "Rel": "GlobalPermissions"
    },
    {
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
      "Rel": "ProjectPermissions"
    }
  ]
}

Status Code

200 - OK

Resource: Group Permission Projects ( /api/group/{id}/permissions/projects )

Returns links to the set of project group permissions resources

This resource supports the following methods: GET

Methods

GET


Retrieves a set of links, one for each project, which can be used to manage the project group permissions for this group.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the group does not exist.

Example - Retrieve project permission links

Retrieve a set of links for managing this groups permissions associated with each project

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the group to retrieve project permission links for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Projects": [
    {
      "ProjectId": "4feb1531-77eb-4393-918f-ed17bc5e12d7",
      "Self": "http://localhost/api/group/3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9/permissions/project/4feb1531-77eb-4393-918f-ed17bc5e12d7",
      "Links": [
        {
          "Title": "Project X",
          "Href": "http://localhost/api/project/4feb1531-77eb-4393-918f-ed17bc5e12d7",
          "Rel": "Project"
        }
      ]
    },
    {
      "ProjectId": "e1a9644c-9d20-44a8-847f-eabff527cebc",
      "Self": "http://localhost/api/group/3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9/permissions/project/e1a9644c-9d20-44a8-847f-eabff527cebc",
      "Links": [
        {
          "Title": "Project Y",
          "Href": "http://localhost/api/project/e1a9644c-9d20-44a8-847f-eabff527cebc",
          "Rel": "Project"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/group/3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9/permissions/projects"
}

Status Code

200 - OK

Resource: Group Permissions ( /api/group/{id}/permissions/global )

Global Group Permissions resource - allows the retrieval of the collection of global permissions directly associated with a group, or updating the permissions associated with a group.

This resource supports the following methods: GET, PUT

Methods

GET


Retrieves the global permissions for this group

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the group does not exist.

Example - Retrieve global permissions

Retrieve the global permissions associated with a group

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the group to retrieve global permissions for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

PUT


Sets the global permissions for this group

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if one or more permissions could not be resolved.
404 - NotFoundReturned if the group does not exist.

Example - Set global permissions

Set the global permissions for a group (using the unique ID for each permission)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the group to retrieve global permissions for

Request Body

[
  {
    "Key": null,
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22"
  },
  {
    "Key": null,
    "Id": "fad12035-4937-401a-881a-ea340050218e"
  }
]

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

Example - Set global permissions

Set the global permissions for a group (using the unique Key for each permission)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the group to retrieve global permissions for

Request Body

[
  {
    "Key": "/Administration",
    "Id": null
  },
  {
    "Key": "/Resources",
    "Id": null
  }
]

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

Resource: Group Users ( /api/group/{id}/users )

Collection resource of users belonging to a group.

This resource supports the following methods: GET, PUT

Methods

GET


Retrieves all (or a subset) of users in a group.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if group does not exist.

Example - Get All Users

An example of fetching all users in group.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}0832C85F-E532-472F-92E1-287995CE3726ID of the group

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "c699d96a-a63b-4087-bc04-c429de15dd53",
    "UserName": "joeb",
    "Email": "joeb@unknown.net",
    "FirstName": "Joe",
    "LastName": "Bloggs",
    "Phone": "(09)-555-999",
    "LastLogIn": null,
    "Enabled": true,
    "IsExternal": false,
    "Self": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53",
    "Links": [
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/password",
        "Rel": "ChangePassword"
      },
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/permissions/global",
        "Rel": "GlobalPermissions"
      },
      {
        "Title": "Group Memberships",
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/groups",
        "Rel": "Groups"
      },
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/notifications",
        "Rel": "Notifications"
      },
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/permissions/projects",
        "Rel": "ProjectPermissions"
      },
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/mailmessages",
        "Rel": "MailMessages"
      }
    ]
  },
  {
    "Id": "35f32f5b-a69e-4b16-a59c-ebfb988b4bf8",
    "UserName": "janed",
    "Email": "janed@unknown.net",
    "FirstName": "Jane",
    "LastName": "Doe",
    "Phone": "(09)-555-999",
    "LastLogIn": null,
    "Enabled": true,
    "IsExternal": false,
    "Self": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8",
    "Links": [
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/password",
        "Rel": "ChangePassword"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/permissions/global",
        "Rel": "GlobalPermissions"
      },
      {
        "Title": "Group Memberships",
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/groups",
        "Rel": "Groups"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/notifications",
        "Rel": "Notifications"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/permissions/projects",
        "Rel": "ProjectPermissions"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/mailmessages",
        "Rel": "MailMessages"
      }
    ]
  }
]

Status Code

200 - OK

Example - Get Users filtered by first name

An example of fetching a set of users by first name belonging to the group, by using the ODATA $filter query parameter.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}0832C85F-E532-472F-92E1-287995CE3726ID of the group
$filterFirstName eq 'Jane'The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=FirstName%20eq%20'Jane'.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "35f32f5b-a69e-4b16-a59c-ebfb988b4bf8",
    "UserName": "janed",
    "Email": "janed@unknown.net",
    "FirstName": "Jane",
    "LastName": "Doe",
    "Phone": "(09)-555-999",
    "LastLogIn": null,
    "Enabled": true,
    "IsExternal": false,
    "Self": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8",
    "Links": [
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/password",
        "Rel": "ChangePassword"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/permissions/global",
        "Rel": "GlobalPermissions"
      },
      {
        "Title": "Group Memberships",
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/groups",
        "Rel": "Groups"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/notifications",
        "Rel": "Notifications"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/permissions/projects",
        "Rel": "ProjectPermissions"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/mailmessages",
        "Rel": "MailMessages"
      }
    ]
  }
]

Status Code

200 - OK

PUT


Sets the users that are members of the group.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if group does not exist.

Example - Set Members

Sets the users who are members of this group.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}0832C85F-E532-472F-92E1-287995CE3726ID of the group

Request Body

{
  "Items": [
    {
      "Id": "c699d96a-a63b-4087-bc04-c429de15dd53"
    },
    {
      "Id": "35f32f5b-a69e-4b16-a59c-ebfb988b4bf8"
    }
  ]
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "c699d96a-a63b-4087-bc04-c429de15dd53",
    "UserName": "joeb",
    "Email": "joeb@unknown.net",
    "FirstName": "Joe",
    "LastName": "Bloggs",
    "Phone": "(09)-555-999",
    "LastLogIn": null,
    "Enabled": true,
    "IsExternal": false,
    "Self": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53",
    "Links": [
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/password",
        "Rel": "ChangePassword"
      },
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/permissions/global",
        "Rel": "GlobalPermissions"
      },
      {
        "Title": "Group Memberships",
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/groups",
        "Rel": "Groups"
      },
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/notifications",
        "Rel": "Notifications"
      },
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/permissions/projects",
        "Rel": "ProjectPermissions"
      },
      {
        "Href": "http://localhost/api/user/c699d96a-a63b-4087-bc04-c429de15dd53/mailmessages",
        "Rel": "MailMessages"
      }
    ]
  },
  {
    "Id": "35f32f5b-a69e-4b16-a59c-ebfb988b4bf8",
    "UserName": "janed",
    "Email": "janed@unknown.net",
    "FirstName": "Jane",
    "LastName": "Doe",
    "Phone": "(09)-555-999",
    "LastLogIn": null,
    "Enabled": true,
    "IsExternal": false,
    "Self": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8",
    "Links": [
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/password",
        "Rel": "ChangePassword"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/permissions/global",
        "Rel": "GlobalPermissions"
      },
      {
        "Title": "Group Memberships",
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/groups",
        "Rel": "Groups"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/notifications",
        "Rel": "Notifications"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/permissions/projects",
        "Rel": "ProjectPermissions"
      },
      {
        "Href": "http://localhost/api/user/35f32f5b-a69e-4b16-a59c-ebfb988b4bf8/mailmessages",
        "Rel": "MailMessages"
      }
    ]
  }
]

Status Code

200 - OK

Resource: Groups ( /api/groups )

Allows the search and retrieval of groups.

Root Relation: Groups

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of groups.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Get All Groups

An example of fetching all groups.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
    "Name": "Admins",
    "Description": "System Administrators",
    "Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
    "Links": [
      {
        "Title": "Members",
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
        "Rel": "Users"
      },
      {
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
        "Rel": "GlobalPermissions"
      },
      {
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
        "Rel": "ProjectPermissions"
      }
    ]
  },
  {
    "Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
    "Name": "QA",
    "Description": "QA Team (Testers + Test Managers)",
    "Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
    "Links": [
      {
        "Title": "Members",
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
        "Rel": "Users"
      },
      {
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
        "Rel": "GlobalPermissions"
      },
      {
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
        "Rel": "ProjectPermissions"
      }
    ]
  }
]

Status Code

200 - OK

Example - Get Groups filtered by group name

An example of fetching a set of groups filtered by name, by using the ODATA $filter query parameter.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterName eq 'QA'The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Name%20eq%20'QA' .

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
    "Name": "QA",
    "Description": "QA Team (Testers + Test Managers)",
    "Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
    "Links": [
      {
        "Title": "Members",
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
        "Rel": "Users"
      },
      {
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
        "Rel": "GlobalPermissions"
      },
      {
        "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
        "Rel": "ProjectPermissions"
      }
    ]
  }
]

Status Code

200 - OK

POST


Create a new group

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if request contained invalid data or would cause a conflict with an existing group record.
404 - NotFoundReturned if group does not exists.

Example - Create new group

Create a new group.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "Id": null,
  "Name": "QA",
  "Description": "QA Team (Testers + Test Managers)"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d

Response Body

{
  "Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
  "Name": "QA",
  "Description": "QA Team (Testers + Test Managers)",
  "Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
  "Links": [
    {
      "Title": "Members",
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
      "Rel": "Users"
    },
    {
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
      "Rel": "GlobalPermissions"
    },
    {
      "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
      "Rel": "ProjectPermissions"
    }
  ]
}

Status Code

201 - Created

Resource: Groups Search ( /api/groupssearch )

Allows the searching of groups by partial match.

Root Relation: GroupsSearch

This resource supports the following methods: GET, POST

Methods

GET


Searches for groups by partial name match

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the group request was able to be satisfied.

Example - Search for groups

An example of fetching all groups.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}8E064E7A-847F-4853-AFFF-2CD1803664D7The ID of the user to fetch group membership for
queryadPartial name to search for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 1,
  "Items": [
    {
      "Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
      "Name": "Admins",
      "Description": "System Administrators",
      "Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
      "Links": [
        {
          "Title": "Members",
          "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
          "Rel": "Users"
        },
        {
          "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
          "Rel": "GlobalPermissions"
        },
        {
          "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
          "Rel": "ProjectPermissions"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Searches for groups by partial name match (using POST to allow large existing value queries)

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the group request was able to be satisfied.

Example - Search for groups

An example of fetching all groups.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}8E064E7A-847F-4853-AFFF-2CD1803664D7The ID of the user to fetch group membership for
queryadPartial name to search for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 1,
  "Items": [
    {
      "Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
      "Name": "Admins",
      "Description": "System Administrators",
      "Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
      "Links": [
        {
          "Title": "Members",
          "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
          "Rel": "Users"
        },
        {
          "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
          "Rel": "GlobalPermissions"
        },
        {
          "Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
          "Rel": "ProjectPermissions"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Resource: Incident ( /api/incident/{id} )

Incident resource

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Delete a incident.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the permissions required to delete the incident have not been met.
404 - NotFoundReturned if incident does not exist.

Example - DELETE

Delete an incident.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610Unique identifier of the incident to update.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves a single incident by its unique Identifier.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view this incident.
404 - NotFoundReturned if no incident with that identifier exists.

Example - GET

Retrieves incident by its unique identifier

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610Unique identifier of the incident to retrieve.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Summary": "Report pagination",
  "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "AssignedTo": "joeb",
  "Description": "Check report pagination works correctly",
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
  "AffectedVersionIds": null,
  "FixedVersionIds": null,
  "ComponentIds": null,
  "ExternalSystemLinkIds": [],
  "CreatedAt": "2012-01-01T14:04:05Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "CreatedBy": "joeb",
  "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "LastUpdatedBy": "joeb",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "ProjectName": "Test Project",
  "IncidentNumber": 0,
  "InternalId": null,
  "VersionNumber": 0,
  "HasAttachments": false,
  "Expands": [
    "Widgets",
    "FieldValues",
    "Project",
    "Comments",
    "ExternalSystemLinks"
  ],
  "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
      "Rel": "Comments"
    },
    {
      "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "Rel": "Project"
    }
  ]
}

Status Code

200 - OK

PUT


Updates an existing incident.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET could not complete request (normally due to a validation failure or the necessary permissions to complete the request have not been met).
404 - NotFoundReturned if the incident does not exist.

Example - PUT (full update)

Example of updating an existing Incident with most fields populated (including custom fields and comments) - Note: when performing a PUT or POST that includes comments, the comments Expand will be automatically applied to the response.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610Unique identifier of the incident to update.
$expandFieldValuesExpand field (we expand the FieldValues to ensure we get it back in the response to creating a new incident.

Request Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "TemporaryId": "6cc26034-6514-44e0-907c-8f4f5eaa85b5",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "Number": 22,
  "Summary": "Report pagination",
  "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "Description": "description",
  "Comments": [
    {
      "Body": "This bug also affects grid pagination on some screens."
    }
  ],
  "WidgetValues": null,
  "FieldValues": {
    "Cycle": "V2.1 Cycle 1"
  }
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Summary": "My New Incident",
  "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "AssignedTo": "joeb",
  "Description": "description",
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
  "AffectedVersionIds": [
    "2b86c434-bdfa-467a-a944-1f3ac05a83cb"
  ],
  "FixedVersionIds": [
    "93588d80-b8cd-465a-847c-b14fa2dee0b8",
    "c09e7115-c55f-4899-856c-1b861143f78b"
  ],
  "ComponentIds": [
    "71917512-da95-4a24-9eb9-b7a6ba9f7346"
  ],
  "ExternalSystemLinkIds": [],
  "CreatedAt": "2012-01-01T14:04:05Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "CreatedBy": "joeb",
  "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "LastUpdatedBy": "joeb",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "ProjectName": "Test Project",
  "IncidentNumber": 0,
  "InternalId": null,
  "VersionNumber": 0,
  "HasAttachments": true,
  "Expands": [
    "Widgets",
    "Project"
  ],
  "FieldValues": {
    "Cycle": "V2.1 Cycle 1"
  },
  "Comments": [
    {
      "Id": "36f8985c-040e-44e6-9340-17a5ce68a086",
      "Body": "This bug also affects grid pagination on some screens.",
      "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "CreatedByUserName": "joeb",
      "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "LastUpdatedByUserName": "joeb",
      "CreatedAt": "2012-02-02T15:05:06Z",
      "LastUpdatedAt": "0001-01-01T00:00:00Z",
      "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comment/36f8985c-040e-44e6-9340-17a5ce68a086",
      "Links": [
        {
          "Href": "http://localhost/api/user/191375f2-ae6e-4b52-8bed-4192e34b6486",
          "Rel": "CreatedBy"
        },
        {
          "Href": "http://localhost/api/user/191375f2-ae6e-4b52-8bed-4192e34b6486",
          "Rel": "LastUpdatedBy"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
      "Rel": "Comments"
    },
    {
      "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "Rel": "Project"
    }
  ]
}

Status Code

200 - OK

Example - PUT (rename incident)

Example of renaming a incident.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610Unique identifier of the incident to update.

Request Body

{ "Name": "Updated name" }

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Summary": "Updated name",
  "AssignedToId": null,
  "AssignedTo": null,
  "Description": null,
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
  "AffectedVersionIds": [
    "2b86c434-bdfa-467a-a944-1f3ac05a83cb"
  ],
  "FixedVersionIds": [
    "93588d80-b8cd-465a-847c-b14fa2dee0b8",
    "c09e7115-c55f-4899-856c-1b861143f78b"
  ],
  "ComponentIds": [
    "71917512-da95-4a24-9eb9-b7a6ba9f7346"
  ],
  "ExternalSystemLinkIds": [],
  "CreatedAt": "2012-01-01T14:04:05Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "CreatedBy": "joeb",
  "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "LastUpdatedBy": "joeb",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "ProjectName": "Test Project",
  "IncidentNumber": 0,
  "InternalId": null,
  "VersionNumber": 0,
  "HasAttachments": false,
  "Expands": [
    "Widgets",
    "FieldValues",
    "Project",
    "Comments",
    "ExternalSystemLinks"
  ],
  "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
      "Rel": "Comments"
    },
    {
      "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "Rel": "Project"
    }
  ]
}

Status Code

200 - OK

Resource: Incident All Relationships ( /api/incident/{id}/allrelationships )

A resource representing the set of relationships belonging to the Incident (includes the full graph of related entities, not just those which can be reached through destination and source->destination directed relationships).

This resource supports the following methods: GET

Methods

GET


Retrieves all relationships

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the relationships associated with this entity.
404 - NotFoundReturned if the entity does not exist.

Example - Retrieve Relationships

Retrieve relationships (the response is a generic example, and does not necessarily represent the type of relationships that would be returned for this Entity Type).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}5E2814AF-1800-4C8F-B7C8-2ED9FADF98D0The ID of the entity to retrieve the relationships for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "EntityId": "8F00D2CE-6243-4956-AF89-60B7B9755A9B",
  "Number": "1",
  "Name": "Some Script",
  "EntityType": "TestScript",
  "AssignedTo": "joeb",
  "Status": "Draft",
  "Priority": "High",
  "Type": "Functional",
  "PackageId": "c232382b-0c66-475b-b59b-8753d4c5377b",
  "PackageName": "Cycle 1",
  "PackageEntityType": "ScriptPackage",
  "PackagePath": "/Script Library/Cycle 1",
  "RelationshipId": null,
  "RelationshipTypeKey": "ScriptToRequirementCoverage",
  "RelationshipType": "Coverage",
  "Relation": "Covered By",
  "RelationshipDirection": "Source -> Destination",
  "CanDelete": true,
  "CanEdit": false,
  "Children": [
    {
      "EntityId": "4155F037-B778-4E9D-B942-0CC237D51038",
      "Number": "2",
      "Name": "Some Requirement",
      "EntityType": "Requirement",
      "AssignedTo": "janed",
      "Status": "Draft",
      "Priority": "Medium",
      "Type": "Functional",
      "PackageId": "454bc5ca-3496-4abb-a69a-919bf5f3ca0b",
      "PackageName": "Cycle 1",
      "PackageEntityType": "RequirementPackage",
      "PackagePath": "/Requirements/Cycle 1",
      "RelationshipId": null,
      "RelationshipTypeKey": "ScriptToRequirementCoverage",
      "RelationshipType": "Coverage",
      "Relation": "Covered By",
      "RelationshipDirection": "Destination -> Source",
      "CanDelete": false,
      "CanEdit": true,
      "Children": [],
      "Links": [
        {
          "Href": "http://localhost/api",
          "Rel": "Entity"
        }
      ]
    }
  ],
  "Links": [
    {
      "Href": "http://localhost/api",
      "Rel": "Entity"
    }
  ]
}

Status Code

200 - OK

Resource: Incident Attachment ( /api/incident/{incidentId}/attachment/{id} )

Allows you to manage a single attachment for a Incident.

This resource supports the following methods: DELETE

Methods

DELETE


Deletes an attachment from the Incident.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you have insufficient permissions to delete the attachment.
404 - NotFoundReturned if the attachment or Incident does not exist.

Example - Delete attachment

Delete an attachment associated with the Incident.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{IncidentId}4A685B80-BC5A-42BE-82E0-616D0E70FF05The unique identifier (GUID) of the Incident the attachment belongs to.
{id}B1105C56-43AB-4F66-AFDE-1135AAC851E5The unique identifier (GUID) of the attachment to delete.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

Resource: Incident Attachments ( /api/incident/{id}/attachments )

Incident Attachments (collection) resource for fetching attachments associated with a Incident, or adding new attachments to the Incident.

This resource supports the following methods: GET, POST

Methods

GET


Retrieves list of attachments for the Incident.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you have insufficient permissions to retrieve attachments.
404 - NotFoundReturned if the Incident was not found.

Example - GET

Retrieves a list of all attachments associated with a Incident.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610Unique identifier of the script.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "9b02c840-c330-4725-b743-b40181420bc2",
      "IncidentId": "ad506e26-dea1-4fba-a2c8-ee993b9f9444",
      "Name": "screenshot 1",
      "FileName": "screenshot1.png",
      "ContentType": "image/png",
      "CreatedAt": "2012-01-01T14:04:05Z",
      "CreatedById": "2b364daa-0dff-4a6f-8554-f5963d3011be",
      "Size": 122454,
      "Self": "http://localhost/api/incident/ad506e26-dea1-4fba-a2c8-ee993b9f9444/attachment/9b02c840-c330-4725-b743-b40181420bc2",
      "Content": "http://localhost/api/attachment/00000000-0000-0000-0000-000000000000/contents"
    },
    {
      "Id": "5669f517-5ef4-40b6-856f-dbd488319da6",
      "IncidentId": "ad506e26-dea1-4fba-a2c8-ee993b9f9444",
      "Name": "notes.txt",
      "FileName": "notes",
      "ContentType": "text/plain",
      "CreatedAt": "2012-01-01T14:04:05Z",
      "CreatedById": "2b364daa-0dff-4a6f-8554-f5963d3011be",
      "Size": 3,
      "Self": "http://localhost/api/incident/ad506e26-dea1-4fba-a2c8-ee993b9f9444/attachment/5669f517-5ef4-40b6-856f-dbd488319da6",
      "Content": "http://localhost/api/attachment/00000000-0000-0000-0000-000000000000/contents"
    }
  ]
}

Status Code

200 - OK

POST


Upload one or more attachments for this Incident.

Required Permissions

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
201 - CreatedReturned if the attachments were uploaded successfully.
403 - ForbiddenReturned if the multipart request did not contain any files.
415 - UnsupportedMediaTypeReturned if the request is not mime multipart.

Example - POST

Uploads one or more files using a mime multipart request (this example shows a response where two files were uploaded).

Request Headers

KeyValueDescription
Content-Typemultipart/mixed; boundary=65bf6b94-c91c-442c-abe7-f41444d7c71f

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610The unique identifier (GUID) of the script to add the attachments to.

Request Body

--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename=screenshot1.png; name="screenshot 1"; size=122454
Content-Type: image/png
Content-Length: 3
...
--65bf6b94-c91c-442c-abe7-f41444d7c71f
Content-Disposition: attachment; filename=notes.txt; name=notes; size=3
Content-Type: text/plain
Content-Length: 3
ABC
--65bf6b94-c91c-442c-abe7-f41444d7c71f--

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "9b02c840-c330-4725-b743-b40181420bc2",
      "IncidentId": "ad506e26-dea1-4fba-a2c8-ee993b9f9444",
      "Name": "screenshot 1",
      "FileName": "screenshot1.png",
      "ContentType": "image/png",
      "CreatedAt": "2012-01-01T14:04:05Z",
      "CreatedById": "2b364daa-0dff-4a6f-8554-f5963d3011be",
      "Size": 122454,
      "Self": "http://localhost/api/incident/ad506e26-dea1-4fba-a2c8-ee993b9f9444/attachment/9b02c840-c330-4725-b743-b40181420bc2",
      "Content": "http://localhost/api/attachment/00000000-0000-0000-0000-000000000000/contents"
    },
    {
      "Id": "5669f517-5ef4-40b6-856f-dbd488319da6",
      "IncidentId": "ad506e26-dea1-4fba-a2c8-ee993b9f9444",
      "Name": "notes.txt",
      "FileName": "notes",
      "ContentType": "text/plain",
      "CreatedAt": "2012-01-01T14:04:05Z",
      "CreatedById": "2b364daa-0dff-4a6f-8554-f5963d3011be",
      "Size": 3,
      "Self": "http://localhost/api/incident/ad506e26-dea1-4fba-a2c8-ee993b9f9444/attachment/5669f517-5ef4-40b6-856f-dbd488319da6",
      "Content": "http://localhost/api/attachment/00000000-0000-0000-0000-000000000000/contents"
    }
  ]
}

Status Code

201 - Created

Resource: Incident Comments ( /api/incident/{id}/comments )

Incident comment collection resource, provides the ability to retrieve all or a subset of comments associated with an incident. Currently to add new comments to an incident, you must update the incident and include a 'Comments' child collection (see the Incident resource examples for more details).

This resource supports the following methods: GET

Methods

GET


Retrieves all (or a subset) of an incident's comments.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you don't have permission to view this incident.
404 - NotFoundReturned if the incident does not exist.

Example - Get all comments

Retrieve a collection of all comments

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a1f57de4-832f-4986-99e1-f026ea2e026fID of the incident to retrieve the comments for.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "1e401c7a-ae50-45c2-b94e-8227eebac854",
      "Body": "I have updated the priority of this to high, it's affecting all our customers",
      "CreatedById": "25e9dd38-475d-483b-9c50-3fafee0389b7",
      "CreatedByUserName": "joeb",
      "LastUpdatedById": "25e9dd38-475d-483b-9c50-3fafee0389b7",
      "LastUpdatedByUserName": "joeb",
      "CreatedAt": "2012-03-03T21:34:22Z",
      "LastUpdatedAt": "0001-01-01T00:00:00Z",
      "Self": "http://localhost/api/incident/a1f57de4-832f-4986-99e1-f026ea2e026f/comment/1e401c7a-ae50-45c2-b94e-8227eebac854",
      "Links": [
        {
          "Href": "http://localhost/api/user/25e9dd38-475d-483b-9c50-3fafee0389b7",
          "Rel": "CreatedBy"
        },
        {
          "Href": "http://localhost/api/user/25e9dd38-475d-483b-9c50-3fafee0389b7",
          "Rel": "LastUpdatedBy"
        }
      ]
    },
    {
      "Id": "2aa4900c-e022-4abd-9e3b-ed764f286867",
      "Body": "Issue is now resolved in feature branch - requires further testing before being released to production.",
      "CreatedById": "25e9dd38-475d-483b-9c50-3fafee0389b7",
      "CreatedByUserName": "joeb",
      "LastUpdatedById": "25e9dd38-475d-483b-9c50-3fafee0389b7",
      "LastUpdatedByUserName": "joeb",
      "CreatedAt": "2012-04-05T00:11:10Z",
      "LastUpdatedAt": "0001-01-01T00:00:00Z",
      "Self": "http://localhost/api/incident/a1f57de4-832f-4986-99e1-f026ea2e026f/comment/2aa4900c-e022-4abd-9e3b-ed764f286867",
      "Links": [
        {
          "Href": "http://localhost/api/user/25e9dd38-475d-483b-9c50-3fafee0389b7",
          "Rel": "CreatedBy"
        },
        {
          "Href": "http://localhost/api/user/25e9dd38-475d-483b-9c50-3fafee0389b7",
          "Rel": "LastUpdatedBy"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Resource: Incident Relationships ( /api/incident/{id}/relationships )

A resource representing the set of relationships belonging to the Incident.

This resource supports the following methods: GET

Methods

GET


Retrieves all relationships

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view the relationships associated with this entity.
404 - NotFoundReturned if the entity does not exist.

Example - Retrieve Relationships

Retrieve relationships (the response is a generic example, and does not necessarily represent the type of relationships that would be returned for this Entity Type).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}5E2814AF-1800-4C8F-B7C8-2ED9FADF98D0The ID of the entity to retrieve the relationships for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "EntityId": "8F00D2CE-6243-4956-AF89-60B7B9755A9B",
  "Number": "1",
  "Name": "Some Script",
  "EntityType": "TestScript",
  "AssignedTo": "joeb",
  "Status": "Draft",
  "Priority": "High",
  "Type": "Functional",
  "PackageId": "c232382b-0c66-475b-b59b-8753d4c5377b",
  "PackageName": "Cycle 1",
  "PackageEntityType": "ScriptPackage",
  "PackagePath": "/Script Library/Cycle 1",
  "RelationshipId": null,
  "RelationshipTypeKey": "ScriptToRequirementCoverage",
  "RelationshipType": "Coverage",
  "Relation": "Covered By",
  "RelationshipDirection": "Source -> Destination",
  "CanDelete": true,
  "CanEdit": false,
  "Children": [
    {
      "EntityId": "4155F037-B778-4E9D-B942-0CC237D51038",
      "Number": "2",
      "Name": "Some Requirement",
      "EntityType": "Requirement",
      "AssignedTo": "janed",
      "Status": "Draft",
      "Priority": "Medium",
      "Type": "Functional",
      "PackageId": "454bc5ca-3496-4abb-a69a-919bf5f3ca0b",
      "PackageName": "Cycle 1",
      "PackageEntityType": "RequirementPackage",
      "PackagePath": "/Requirements/Cycle 1",
      "RelationshipId": null,
      "RelationshipTypeKey": "ScriptToRequirementCoverage",
      "RelationshipType": "Coverage",
      "Relation": "Covered By",
      "RelationshipDirection": "Destination -> Source",
      "CanDelete": false,
      "CanEdit": true,
      "Children": [],
      "Links": [
        {
          "Href": "http://localhost/api",
          "Rel": "Entity"
        }
      ]
    }
  ],
  "Links": [
    {
      "Href": "http://localhost/api",
      "Rel": "Entity"
    }
  ]
}

Status Code

200 - OK

Resource: Incidents ( /api/incidents )

Incidents collection resource

Root Relation: Incidents

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of incidents that are visible.

This method supports the TQL query parameters tql, $top, $take and $inlinecount. See TQL Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if ET would not complete request (normally due to a validation failure or the necessary permissions to complete the request have not been met).

Example - GET (filtered by TQL Query)

Retrieves all incidents matching a TQL query.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
tqlName ~ 'Report'The TQL query to execute.
$top5Maximum number of results to return (defaults to 25).
$skip0Number of results to skip before return the $top number of results matching the query.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 1,
  "Items": [
    {
      "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Summary": "Report pagination",
      "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "AssignedTo": "joeb",
      "Description": "Check report pagination works correctly",
      "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
      "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
      "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
      "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
      "AffectedVersionIds": null,
      "FixedVersionIds": null,
      "ComponentIds": null,
      "ExternalSystemLinkIds": [],
      "CreatedAt": "2012-01-01T14:04:05Z",
      "LastUpdatedAt": "2012-02-02T15:05:06Z",
      "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "CreatedBy": "joeb",
      "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "LastUpdatedBy": "joeb",
      "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "ProjectName": "Test Project",
      "IncidentNumber": 0,
      "InternalId": null,
      "VersionNumber": 0,
      "HasAttachments": false,
      "Expands": [
        "Widgets",
        "FieldValues",
        "Project",
        "Comments",
        "ExternalSystemLinks"
      ],
      "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Links": [
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
          "Rel": "Comments"
        },
        {
          "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
          "Rel": "Project"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/incidents?tql=Name~'Report'&$top=5&$skip=0"
}

Status Code

200 - OK

Example - GET (no filter)

Retrieves all incidents.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$top5Maximum number of results to return (defaults to 25).
$skip0Number of results to skip before return the $top number of results matching the query.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 5,
  "Total": 2,
  "Items": [
    {
      "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Summary": "Report pagination",
      "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "AssignedTo": "joeb",
      "Description": "Check report pagination works correctly",
      "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
      "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
      "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
      "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
      "AffectedVersionIds": null,
      "FixedVersionIds": null,
      "ComponentIds": null,
      "ExternalSystemLinkIds": [],
      "CreatedAt": "2012-01-01T14:04:05Z",
      "LastUpdatedAt": "2012-02-02T15:05:06Z",
      "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "CreatedBy": "joeb",
      "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "LastUpdatedBy": "joeb",
      "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "ProjectName": "Test Project",
      "IncidentNumber": 0,
      "InternalId": null,
      "VersionNumber": 0,
      "HasAttachments": false,
      "Expands": [
        "Widgets",
        "FieldValues",
        "Project",
        "Comments",
        "ExternalSystemLinks"
      ],
      "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Links": [
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
          "Rel": "Comments"
        },
        {
          "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
          "Rel": "Project"
        }
      ]
    },
    {
      "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Summary": "Login",
      "AssignedToId": null,
      "AssignedTo": null,
      "Description": "Check report pagination works correctly",
      "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
      "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
      "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
      "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
      "AffectedVersionIds": null,
      "FixedVersionIds": null,
      "ComponentIds": null,
      "ExternalSystemLinkIds": [],
      "CreatedAt": "2012-03-01T14:04:05Z",
      "LastUpdatedAt": "2012-03-02T15:05:06Z",
      "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "CreatedBy": "joeb",
      "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "LastUpdatedBy": "joeb",
      "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "ProjectName": "Test Project",
      "IncidentNumber": 0,
      "InternalId": null,
      "VersionNumber": 0,
      "HasAttachments": false,
      "Expands": [
        "Widgets",
        "FieldValues",
        "Project",
        "Comments",
        "ExternalSystemLinks"
      ],
      "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
      "Links": [
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
          "Rel": "Relationships"
        },
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
          "Rel": "AllRelationships"
        },
        {
          "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
          "Rel": "Comments"
        },
        {
          "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
          "Rel": "Project"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/incidents?$top=5&$skip=0"
}

Status Code

200 - OK

POST


Creates a new test incident.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Create Incident with minimum required fields

Example of creating a new incident with the minimum required information.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "Summary": "My New Incident",
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "WidgetValues": null,
  "FieldValues": null
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Summary": "My New Incident",
  "AssignedToId": null,
  "AssignedTo": null,
  "Description": null,
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
  "AffectedVersionIds": null,
  "FixedVersionIds": null,
  "ComponentIds": null,
  "ExternalSystemLinkIds": [],
  "CreatedAt": "2012-01-01T14:04:05Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "CreatedBy": "joeb",
  "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "LastUpdatedBy": "joeb",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "ProjectName": "Test Project",
  "IncidentNumber": 0,
  "InternalId": null,
  "VersionNumber": 0,
  "HasAttachments": false,
  "Expands": [
    "Widgets",
    "FieldValues",
    "Project",
    "Comments",
    "ExternalSystemLinks"
  ],
  "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
      "Rel": "Comments"
    },
    {
      "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "Rel": "Project"
    }
  ]
}

Status Code

201 - Created

Example - Create Incident with most fields populated

Example of creating an new Incident with most fields populated (including custom fields and comments) - Note: when performing a PUT or POST that includes comments, the comments Expand will be automatically applied to the response.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Parameters

KeyValueDescription
$expandFieldValuesExpand field (we expand the FieldValues to ensure that they are included in the response to creating a new incident.

Request Body

{
  "TemporaryId": "6cc26034-6514-44e0-907c-8f4f5eaa85b5",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "Number": 22,
  "Summary": "My New Incident",
  "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
  "Description": "description",
  "ExternalSystemLinkIds": [
    "8fd5de1b-bd94-46db-90e8-d8f24f130f88"
  ],
  "Comments": [
    {
      "Body": "This bug needs to be resolved before the next release."
    }
  ],
  "WidgetValues": null,
  "FieldValues": {
    "Cycle": "V2.1 Cycle 1"
  }
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Summary": "My New Incident",
  "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "AssignedTo": "joeb",
  "Description": "description",
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
  "AffectedVersionIds": null,
  "FixedVersionIds": null,
  "ComponentIds": null,
  "ExternalSystemLinkIds": [
    "8fd5de1b-bd94-46db-90e8-d8f24f130f88"
  ],
  "CreatedAt": "2012-01-01T14:04:05Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "CreatedBy": "joeb",
  "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "LastUpdatedBy": "joeb",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "ProjectName": "Test Project",
  "IncidentNumber": 0,
  "InternalId": null,
  "VersionNumber": 0,
  "HasAttachments": true,
  "Expands": [
    "Widgets",
    "Project"
  ],
  "FieldValues": {
    "Cycle": "V2.1 Cycle 1"
  },
  "Comments": [
    {
      "Id": "36f8985c-040e-44e6-9340-17a5ce68a086",
      "Body": "This bug needs to be resolved before the next release.",
      "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "CreatedByUserName": "joeb",
      "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "LastUpdatedByUserName": "joeb",
      "CreatedAt": "2012-02-02T15:05:06Z",
      "LastUpdatedAt": "0001-01-01T00:00:00Z",
      "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comment/36f8985c-040e-44e6-9340-17a5ce68a086",
      "Links": [
        {
          "Href": "http://localhost/api/user/191375f2-ae6e-4b52-8bed-4192e34b6486",
          "Rel": "CreatedBy"
        },
        {
          "Href": "http://localhost/api/user/191375f2-ae6e-4b52-8bed-4192e34b6486",
          "Rel": "LastUpdatedBy"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
      "Rel": "Comments"
    },
    {
      "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "Rel": "Project"
    }
  ]
}

Status Code

201 - Created

Example - Create incident with external system link specified by name

Example of creating a new Incident with the link specified by name, using the ExternalSystemLinks property.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Parameters

KeyValueDescription
$expandFieldValuesExpand field (we expand the FieldValues to ensure that they are included in the response to creating a new incident.

Request Body

{
  "TemporaryId": "6cc26034-6514-44e0-907c-8f4f5eaa85b5",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "Number": 22,
  "Summary": "My New Incident",
  "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
  "Description": "description",
  "ExternalSystemLinks": [
    {
      "Name": "Jira Bugs"
    }
  ],
  "Comments": [
    {
      "Body": "This bug needs to be resolved before the next release."
    }
  ],
  "WidgetValues": null,
  "FieldValues": {
    "Cycle": "V2.1 Cycle 1"
  }
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Summary": "My New Incident",
  "AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "AssignedTo": "joeb",
  "Description": "description",
  "PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
  "StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
  "TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
  "ResolutionId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
  "AffectedVersionIds": null,
  "FixedVersionIds": null,
  "ComponentIds": null,
  "ExternalSystemLinkIds": [
    "8fd5de1b-bd94-46db-90e8-d8f24f130f88"
  ],
  "CreatedAt": "2012-01-01T14:04:05Z",
  "LastUpdatedAt": "2012-02-02T15:05:06Z",
  "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "CreatedBy": "joeb",
  "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
  "LastUpdatedBy": "joeb",
  "ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
  "ProjectName": "Test Project",
  "IncidentNumber": 0,
  "InternalId": null,
  "VersionNumber": 0,
  "HasAttachments": true,
  "Expands": [
    "Widgets",
    "Project"
  ],
  "FieldValues": {
    "Cycle": "V2.1 Cycle 1"
  },
  "Comments": [
    {
      "Id": "36f8985c-040e-44e6-9340-17a5ce68a086",
      "Body": "This bug needs to be resolved before the next release.",
      "CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "CreatedByUserName": "joeb",
      "LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
      "LastUpdatedByUserName": "joeb",
      "CreatedAt": "2012-02-02T15:05:06Z",
      "LastUpdatedAt": "0001-01-01T00:00:00Z",
      "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comment/36f8985c-040e-44e6-9340-17a5ce68a086",
      "Links": [
        {
          "Href": "http://localhost/api/user/191375f2-ae6e-4b52-8bed-4192e34b6486",
          "Rel": "CreatedBy"
        },
        {
          "Href": "http://localhost/api/user/191375f2-ae6e-4b52-8bed-4192e34b6486",
          "Rel": "LastUpdatedBy"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
      "Rel": "Relationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
      "Rel": "AllRelationships"
    },
    {
      "Href": "http://localhost/api/incident/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
      "Rel": "Comments"
    },
    {
      "Href": "http://localhost/api/project/27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
      "Rel": "Project"
    }
  ]
}

Status Code

201 - Created

Resource: Latest Performance Measurement ( /api/diagnostics/performancemeasurement/latest )

Allows retrieving of latest performance measurement

This resource supports the following methods: GET

Methods

GET


Returns results of last performance test run since server was started.

Required Permissions

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
200 - OKReturned if the report was generated successfully.
403 - ForbiddenReturned if the user does not have permission to run diagnostic tests.
404 - NotFoundReturned if the performance test has not been run, or first test is still in progress.

Resource: Mail Queue Messages ( /api/mailqueue/messages )

Allows the retrieval of messages awaiting delivery in the mail queue (collection resource)

Root Relation: MailQueueMessages

This resource supports the following methods: GET

Methods

GET


Retrieves mail messages queued for delivery.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to retrieve items in the mail queue.

Example - Get page of mail messages

Example of fetching the first page of mail messages

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$skip0
$top25

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "Id": "abfa25fc-87ef-4a6a-8320-c933b5d3c8c7",
      "EnqueuedAt": "2013-01-01T14:04:05Z",
      "Subject": "This is the subject (title) of the email",
      "Body": "This is the body of the email",
      "To": [
        {
          "Address": "joeb@test.com",
          "Name": "Joe Bloggs"
        }
      ],
      "Self": "http://localhost/api/mailqueue/message/abfa25fc-87ef-4a6a-8320-c933b5d3c8c7"
    },
    {
      "Id": "66181f42-02b5-44a8-988b-13ad5e8deb80",
      "EnqueuedAt": "2013-01-01T14:04:06Z",
      "Subject": "This is the subject (title) of another email message",
      "Body": "This is another email message body\r\nThat spans\r\nMultiple lines",
      "To": [
        {
          "Address": "joeb@test.com",
          "Name": "Joe Bloggs"
        },
        {
          "Address": "janed@test.com",
          "Name": "Jane Doe"
        }
      ],
      "Self": "http://localhost/api/mailqueue/message/66181f42-02b5-44a8-988b-13ad5e8deb80"
    }
  ],
  "Self": "http://localhost/api/api/mailqueue/messages?$skip=0&$top=25"
}

Status Code

200 - OK

Resource: Mail Sender Settings ( /api/mailsender/default/settings )

Allows the retrieval of the mail sender (using SMTP) settings that Enterprise Tester will use when sending e-mail notifications.

Root Relation: DefaultMailsenderSettings

This resource supports the following methods: GET, PUT

Methods

GET


Retrieves default mail sender settings.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to retrieve the mail sender settings.

Example - Get SMTP settings

Example of fetching current mail sender (SMTP) settings

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Enabled": true,
  "Type": "SMTP",
  "FromAddress": "noreply@corp.com",
  "EmailPrefix": "[ET]",
  "HostName": "smtp.corp.com",
  "Port": null,
  "Timeout": 10000,
  "SSL": true,
  "UserName": "etmail",
  "Password": "etpwd",
  "Self": "http://localhost/apimailsender/default/settings"
}

Status Code

200 - OK

PUT


Updates default mail sender settings

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to update the mail sender settings.

Example - Update SMTP settings

Example of updating smtp settings for application.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "Enabled": true,
  "Type": "SMTP",
  "FromAddress": "noreply@corp.com",
  "EmailPrefix": "[ET]",
  "HostName": "smtp.corp.com",
  "Port": null,
  "Timeout": 10000,
  "SSL": true,
  "UserName": "etmail",
  "Password": "etpwd"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Enabled": true,
  "Type": "SMTP",
  "FromAddress": "noreply@corp.com",
  "EmailPrefix": "[ET]",
  "HostName": "smtp.corp.com",
  "Port": null,
  "Timeout": 10000,
  "SSL": true,
  "UserName": "etmail",
  "Password": "etpwd",
  "Self": "http://localhost/apimailsender/default/settings"
}

Status Code

200 - OK

Resource: Notification ( /api/user/{userId}/notification/{notificationId} )

Resource representing a single notification message for a user.

This resource supports the following methods: DELETE, GET, PATCH

Methods

DELETE


Deletes a single notification message

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to delete notifications for this user.
404 - NotFoundReturned if notification message was not found.

Example - Delete a notification message

Removes a notification from the users collection of in-app notifications

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}32B00F17-D492-4DAD-AD6A-DEBD61EFA119ID of the user whose in-box the notification belongs to.
{notificationId}2E2A2B7F-EEEA-4649-8F34-4A841426F27BID of the notification message

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves information about a single notification message.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to view notifications for this user.
404 - NotFoundReturned if notification message was not found.

Example - Get individual notification

Retrieves a notification identified by it's user and notification identifier

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}32B00F17-D492-4DAD-AD6A-DEBD61EFA119ID of the user whose in-box the notification belongs to.
{notificationId}2E2A2B7F-EEEA-4649-8F34-4A841426F27BID of the notification message

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "OccurredAt": "2012-01-01T14:04:05Z",
  "Id": "2e2a2b7f-eeea-4649-8f34-4a841426f27b",
  "HtmlSummary": "Joe Bloggs has created requirement 'All close buttons should be red'",
  "Viewed": false,
  "IconClass": "requirement-icon",
  "IconTitle": "Requirement",
  "Self": "http://localhost/api/user/32b00f17-d492-4dad-ad6a-debd61efa119/notification/2e2a2b7f-eeea-4649-8f34-4a841426f27b"
}

Status Code

200 - OK

PATCH


Patch an existing notification message (Allows updating the Viewed property)

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to mark this notification message as being viewed.

Example - Patch notification's 'Viewed' property

Marks the notification as having been viewed by the user (will cause message to be displayed in grey color within the in-app notifications inbox)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}32B00F17-D492-4DAD-AD6A-DEBD61EFA119ID of the user whose in-box the notification belongs to.
{notificationId}2E2A2B7F-EEEA-4649-8F34-4A841426F27BID of the notification message

Request Body

{
  "Viewed": true
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "OccurredAt": "2012-01-01T14:04:05Z",
  "Id": "2e2a2b7f-eeea-4649-8f34-4a841426f27b",
  "HtmlSummary": "Joe Bloggs has created requirement 'All close buttons should be red'",
  "Viewed": true,
  "IconClass": "requirement-icon",
  "IconTitle": "Requirement",
  "Self": "http://localhost/api/user/32b00f17-d492-4dad-ad6a-debd61efa119/notification/2e2a2b7f-eeea-4649-8f34-4a841426f27b"
}

Status Code

200 - OK

Resource: Notifications ( /api/user/{userId}/notifications )

Resource representing the collection of notification messages for a user.

This resource supports the following methods: DELETE, GET, POST

Methods

DELETE


Clears all notifications for the user

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to delete notifications for this user.

Example - Delete all notifications

Deletes all notifications for a user (allows immediately clearing of all notifications, both read and unread).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}3BB1CDC3-2ADB-46C3-B5E3-7A6208A8E10DUnique identifier of the User

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves notification messages for a user.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to view notifications for this user.

Example - Retrieve notifications for user

Retrieve the notifications for a user (read and un read) ordered in Date descending order

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}f545f3ae-f35c-4677-b516-c5c740f2a8cfUnique identifier of the User

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "OccurredAt": "2012-11-11T15:38:00Z",
      "Id": "386429b0-5b4f-4422-ac09-a1070122baee",
      "HtmlSummary": "Joe Blogs deleted Requirement 'Weapons must use antimater'",
      "Viewed": true,
      "IconClass": "requirement-icon",
      "IconTitle": "Requirement",
      "Self": "http://localhost/api/user/f545f3ae-f35c-4677-b516-c5c740f2a8cf/notification/386429b0-5b4f-4422-ac09-a1070122baee"
    },
    {
      "OccurredAt": "2012-11-11T15:37:23Z",
      "Id": "71f38117-f39e-48f7-a3d4-7486047ac199",
      "HtmlSummary": "Joe Blogs updated Requirement '<a href=\"http://myserver/EnterpriseTester/home#/requirement/edit/8f5a4b01-ef57-4910-b1a2-a10101632917\">Weapons must use anti-matter</a>'",
      "Viewed": false,
      "IconClass": "requirement-icon",
      "IconTitle": "Requirement",
      "Self": "http://localhost/api/user/f545f3ae-f35c-4677-b516-c5c740f2a8cf/notification/71f38117-f39e-48f7-a3d4-7486047ac199"
    }
  ],
  "UnviewedTotal": 1,
  "Self": "http://localhost/api/api/user/F545F3AE-F35C-4677-B516-C5C740F2A8CF/notifications"
}

Status Code

200 - OK

POST


Create a new notification for the user (users can create notifications for themselves without any permissions, otherwise Administrative permissions are required for the organisation)

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if the user does not have permission to create a notification for this user.

Example - Create a new notification message for this user

Creates a new notification message for this user

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}f545f3ae-f35c-4677-b516-c5c740f2a8cfUnique identifier of the User

Request Body

{
  "HtmlSummary": "Reminder - <a href=\"http://mywiki/projectx?page=sprint1\" target=\"_blank\">Sprint 1</a> finishes tomorrow!"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "OccurredAt": "2012-11-11T15:37:23Z",
  "Id": "2fba775e-c8f7-468d-9ad2-e9f4f6631130",
  "HtmlSummary": "Reminder - <a href=\"http://mywiki/projectx?page=sprint1\" target=\"_blank\">Sprint 1</a> finishes tomorrow!",
  "Viewed": false,
  "IconClass": "notification-message-icon",
  "IconTitle": "Alert",
  "Self": "http://localhost/api/user/f545f3ae-f35c-4677-b516-c5c740f2a8cf/notification/2fba775e-c8f7-468d-9ad2-e9f4f6631130"
}

Status Code

201 - Created

Resource: Organisation ( /api/organisation/{id} )

Resource representing a single organisation. Currently Enterprise Tester only supports a single organisation, so the unique orgranisation identifier can be omitted to return the default project when interacting with this resource.

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Start a background task to delete a organisation

Required Permissions

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 started successfully.
404 - NotFoundReturned if project was not found.

GET


Retrieves information about a single organisation.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if organisation was not found.

Example - Get organisation by ID

Retrieve organisation identified by its unique identifier.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}A84DE3D2-6B49-41C4-AD1D-C937338B0E31Unique identifier of organisation.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "a84de3d2-6b49-41c4-ad1d-c937338b0e31",
  "Name": "Acme Inc",
  "OrderNumber": 1,
  "ShortDescription": "Acme Inc make products",
  "LongDescription": "Acme Inc make products large and small, for many verticals and horizontals.",
  "IndustryType": "Generics",
  "Expands": [
    "Components",
    "IncidentResolutions",
    "IncidentStatuses",
    "IncidentTypes",
    "Priorities",
    "ProjectCategories",
    "Projects",
    "RequirementDifficulties",
    "RequirementStatuses",
    "RequirementTypes",
    "Statuses",
    "TestTypes",
    "Versions"
  ],
  "Self": "http://localhost/api/organisation/a84de3d2-6b49-41c4-ad1d-c937338b0e31"
}

Status Code

200 - OK

Example - Get default organisation

Retrieves the default organisation by omitting any unique identifier (Currently all Enterprise Tester installations have a maximum of 1 organisation, so this will return the only organisation).

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "a84de3d2-6b49-41c4-ad1d-c937338b0e31",
  "Name": "Acme Inc",
  "OrderNumber": 1,
  "ShortDescription": "Acme Inc make products",
  "LongDescription": "Acme Inc make products large and small, for many verticals and horizontals",
  "IndustryType": "Generics",
  "Expands": [
    "Components",
    "IncidentResolutions",
    "IncidentStatuses",
    "IncidentTypes",
    "Priorities",
    "ProjectCategories",
    "Projects",
    "RequirementDifficulties",
    "RequirementStatuses",
    "RequirementTypes",
    "Statuses",
    "TestTypes",
    "Versions"
  ],
  "Self": "http://localhost/api/organisation/a84de3d2-6b49-41c4-ad1d-c937338b0e31"
}

Status Code

200 - OK

PUT


Update details for an organisation.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if request can not be satisified (invalid values, or insufficient permissions).
404 - NotFoundReturned if organisation was not found.

Example - Update organisation details

Update organisation details.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "Name": "XYZ Corp",
  "OrderNumber": 2,
  "ShortDescription": "XYZ Corp integrate systems",
  "LongDescription": "XYZ Corp can integrate any X with any Y to make a Z",
  "IndustryType": "Integration"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "a84de3d2-6b49-41c4-ad1d-c937338b0e31",
  "Name": "XYZ Corp",
  "OrderNumber": 2,
  "ShortDescription": "XYZ Corp integrate systems",
  "LongDescription": "XYZ Corp can integrate any X with any Y to make a Z",
  "IndustryType": "Integration",
  "Expands": [
    "Components",
    "IncidentResolutions",
    "IncidentStatuses",
    "IncidentTypes",
    "Priorities",
    "ProjectCategories",
    "Projects",
    "RequirementDifficulties",
    "RequirementStatuses",
    "RequirementTypes",
    "Statuses",
    "TestTypes",
    "Versions"
  ],
  "Self": "http://localhost/api/organisation/a84de3d2-6b49-41c4-ad1d-c937338b0e31"
}

Status Code

200 - OK

Resource: Organisation Picklist ( /api/organisation/{organisationId}/picklist/{type} )

Used to retrieve the picklist values associated with an organisation (values which are copied/inherited into new projects)

This resource supports the following methods: GET

Methods

GET


Retrieve picklist values for the organisation.

Required Permissions

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
200 - OKReturned if the picklist values were retrieved successfully.
404 - NotFoundReturned if the organisation does not exist.

Example - Retrieve all picklist values

Retrieve all picklist value for the picklist 'Priority'.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{organisationId}bc692c60-99b2-4df3-8cf8-74f4ac770b16Unique ID of the organisation related to the picklist values.
{type}PriorityThe picklist type e.g. RequirementType,RequirementStatus,Priority,RequirementDifficulty etc.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "2fe983c7-bc0d-430f-83f2-9a97863e4891",
      "Text": "High",
      "SortOrder": 0,
      "Self": "http://localhost/api/organisation/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/2fe983c7-bc0d-430f-83f2-9a97863e4891"
    },
    {
      "Id": "fb82918b-cb0e-4c38-b994-bc35f469d020",
      "Text": "Medium",
      "SortOrder": 1,
      "Self": "http://localhost/api/organisation/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/fb82918b-cb0e-4c38-b994-bc35f469d020"
    },
    {
      "Id": "b6a3cb4d-638b-4803-9cf5-bc9830e29835",
      "Text": "Low",
      "SortOrder": 2,
      "Self": "http://localhost/api/organisation/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/b6a3cb4d-638b-4803-9cf5-bc9830e29835"
    }
  ],
  "Self": "http://localhost/api/api/organisation/BC692C60-99B2-4DF3-8CF8-74F4AC770B16/picklist/Priority"
}

Status Code

200 - OK

Resource: Organisation Picklist Search ( /api/organisation/{organisationId}/picklistsearch/{type} )

Allows the searching of picklist values for an organisation by partial name match.

This resource supports the following methods: GET, POST

Methods

GET


Searches for picklist values by partial name match

Required Permissions

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
200 - OKReturned if the picklist values were retrieved successfully.
403 - ForbiddenReturned if the user does not have permission to view picklist values for this project.
404 - NotFoundReturned if the organisation does not exist.

Example - Search for picklist values

Search for picklist values by partial name

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{organisationId}bc692c60-99b2-4df3-8cf8-74f4ac770b16Unique ID of the organisation related to the picklist values.
{type}PriorityThe picklist type e.g. RequirementType,RequirementStatus,Priority,RequirementDifficulty etc.
queryHThe partial name to search for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "2fe983c7-bc0d-430f-83f2-9a97863e4891",
      "Text": "High",
      "SortOrder": 0,
      "Self": "http://localhost/api/organisation/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/2fe983c7-bc0d-430f-83f2-9a97863e4891"
    }
  ],
  "Self": "http://localhost/api/api/organisation/BC692C60-99B2-4DF3-8CF8-74F4AC770B16/picklistsearch/Priority?query=H"
}

Status Code

200 - OK

POST


Searches for picklist values by partial name match (using POST to allow large existing value queries)

Required Permissions

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
200 - OKReturned if the picklist values were retrieved successfully.
403 - ForbiddenReturned if the user does not have permission to view picklist values for this project.
404 - NotFoundReturned if the organisation does not exist.

Example - Search for picklist values

Search for picklist values by partial name

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{organisationId}bc692c60-99b2-4df3-8cf8-74f4ac770b16Unique ID of the organisation related to the picklist values.
{type}PriorityThe picklist type e.g. RequirementType,RequirementStatus,Priority,RequirementDifficulty etc.
queryHThe partial name to search for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "2fe983c7-bc0d-430f-83f2-9a97863e4891",
      "Text": "High",
      "SortOrder": 0,
      "Self": "http://localhost/api/organisation/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/2fe983c7-bc0d-430f-83f2-9a97863e4891"
    }
  ],
  "Self": "http://localhost/api/api/organisation/BC692C60-99B2-4DF3-8CF8-74F4AC770B16/picklistsearch/Priority"
}

Status Code

200 - OK

Resource: Organisation Relationship Types ( /api/organisation/{id}/relationshiptypes )

Allows retrieving of all relationship types associated with a single organisation.

This resource supports the following methods: GET

Methods

GET


Retrieves all relationship types

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the organisation does not exist.

Example - Retrieve all relationship types

Retrieves all the relationship types

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}e12cce32-7029-4083-99dd-51aed6fd8adbID of Organisation to fetch relationship types for.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "CanCreateRelationshipsOfThisType": true,
      "CanDeleteRelationshipsOfThisType": true,
      "CanEditRelationshipsOfThisType": true,
      "DestinationToSourceLabel": "Associated",
      "SourceToDestinationLabel": "Associated",
      "OrganisationId": "e12cce32-7029-4083-99dd-51aed6fd8adb",
      "Key": "RequirementToRequirementAssociation",
      "Name": "Association (Requirement <-> Requirement)",
      "SourceEntityType": "Requirement",
      "DestinationEntityType": "Requirement",
      "AllowableDirections": [
        {
          "Id": "0",
          "Name": "None"
        },
        {
          "Id": "1",
          "Name": "Source -> Destination"
        },
        {
          "Id": "2",
          "Name": "Destination -> Source"
        },
        {
          "Id": "3",
          "Name": "Source <-> Destination"
        }
      ],
      "Self": "http://localhost/api/organisation/e12cce32-7029-4083-99dd-51aed6fd8adb/relationshiptype/RequirementToRequirementAssociation",
      "Links": [
        {
          "Href": "http://localhost/api/organisation/e12cce32-7029-4083-99dd-51aed6fd8adb",
          "Rel": "Organisation"
        },
        {
          "Href": "http://localhost/api/organisation/e12cce32-7029-4083-99dd-51aed6fd8adb/relationshiptype/RequirementToRequirementAssociation/relationships",
          "Rel": "CreateRelationship"
        }
      ]
    },
    {
      "CanCreateRelationshipsOfThisType": true,
      "CanDeleteRelationshipsOfThisType": true,
      "CanEditRelationshipsOfThisType": false,
      "DestinationToSourceLabel": "Covered By",
      "SourceToDestinationLabel": "Covers",
      "OrganisationId": "e12cce32-7029-4083-99dd-51aed6fd8adb",
      "Key": "ScriptToRequirementCoverage",
      "Name": "Coverage (TestScript <-> Requirement)",
      "SourceEntityType": "TestScript",
      "DestinationEntityType": "Requirement",
      "AllowableDirections": [
        {
          "Id": "1",
          "Name": "Source -> Destination"
        }
      ],
      "Self": "http://localhost/api/organisation/e12cce32-7029-4083-99dd-51aed6fd8adb/relationshiptype/ScriptToRequirementCoverage",
      "Links": [
        {
          "Href": "http://localhost/api/organisation/e12cce32-7029-4083-99dd-51aed6fd8adb",
          "Rel": "Organisation"
        },
        {
          "Href": "http://localhost/api/organisation/e12cce32-7029-4083-99dd-51aed6fd8adb/relationshiptype/ScriptToRequirementCoverage/relationships",
          "Rel": "CreateRelationship"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Resource: Organisations ( /api/organisations )

Organisations (collection) resource

Root Relation: Organisations

This resource supports the following methods: GET, POST

Methods

GET


Retrieves a list of all organisations.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Get all organisations

Retrieves all organisations.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "a84de3d2-6b49-41c4-ad1d-c937338b0e31",
      "Name": "Acme Inc",
      "OrderNumber": 1,
      "ShortDescription": "Acme Inc make products",
      "LongDescription": "Acme Inc make products large and small, for many verticals and horizontals",
      "IndustryType": "Generics",
      "Expands": [
        "Components",
        "IncidentResolutions",
        "IncidentStatuses",
        "IncidentTypes",
        "Priorities",
        "ProjectCategories",
        "Projects",
        "RequirementDifficulties",
        "RequirementStatuses",
        "RequirementTypes",
        "Statuses",
        "TestTypes",
        "Versions"
      ],
      "Self": "http://localhost/api/organisation/a84de3d2-6b49-41c4-ad1d-c937338b0e31"
    }
  ]
}

Status Code

200 - OK

POST


Create a new organisation.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the request was completed successfully.
403 - ForbiddenReturned if request can not be satisified (invalid values, or insufficient permissions).

Example - Create a new organisation

Creates a new organisation (if your license allows it)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "Name": "Acme Inc",
  "ShortDescription": "Acme Inc make products",
  "LongDescription": "Acme Inc make products large and small, for many verticals and horizontals",
  "IndustryType": "Generics"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8
Locationhttp://localhost/api/organisation/A84DE3D2-6B49-41C4-AD1D-C937338B0E31

Response Body

{
  "Id": "a84de3d2-6b49-41c4-ad1d-c937338b0e31",
  "Name": "Acme Inc",
  "OrderNumber": 1,
  "ShortDescription": "Acme Inc make products",
  "LongDescription": "Acme Inc make products large and small, for many verticals and horizontals",
  "IndustryType": "Generics",
  "Expands": [
    "Components",
    "IncidentResolutions",
    "IncidentStatuses",
    "IncidentTypes",
    "Priorities",
    "ProjectCategories",
    "Projects",
    "RequirementDifficulties",
    "RequirementStatuses",
    "RequirementTypes",
    "Statuses",
    "TestTypes",
    "Versions"
  ],
  "Self": "http://localhost/api/organisation/a84de3d2-6b49-41c4-ad1d-c937338b0e31"
}

Status Code

201 - Created

Resource: Permission ( /api/permission/{id} )

Permission resource.

This resource supports the following methods: GET

Methods

GET


Retrieves a permission by it's unique ID.

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
200 - OKReturned if the request was completed successfully.

Example - Retrieve a permission (and all it's children)

Returns a single permission identified by it's unique ID

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}16342c78-d2ec-4436-a9c3-aaa105cafda4Unique ID of the permission to retrieve

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "16342c78-d2ec-4436-a9c3-aaa105cafda4",
  "Key": "/Resources",
  "Name": "Resources",
  "Children": [
    {
      "Id": "38d05448-09f7-4a13-b091-bc271d148246",
      "Key": "/Resources/ExternalLinks",
      "Name": "External Links",
      "Children": [],
      "Self": "http://localhost/api/permission/38d05448-09f7-4a13-b091-bc271d148246"
    }
  ],
  "Self": "http://localhost/api/permission/16342c78-d2ec-4436-a9c3-aaa105cafda4"
}

Status Code

200 - OK

Resource: Permissions ( /api/permissions )

Permissions (collection) resource.

Root Relation: Permissions

This resource supports the following methods: GET

Methods

GET


Retrieves list of permissions (including all child permissions).

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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
200 - OKReturned if the request was completed successfully.

Example - Retrieve all permissions

Returns a collection of all permissions (including all nested permissions)

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "16342c78-d2ec-4436-a9c3-aaa105cafda4",
      "Key": "/Resources",
      "Name": "Resources",
      "Children": [
        {
          "Id": "38d05448-09f7-4a13-b091-bc271d148246",
          "Key": "/Resources/ExternalLinks",
          "Name": "External Links",
          "Children": [],
          "Self": "http://localhost/api/permission/38d05448-09f7-4a13-b091-bc271d148246"
        }
      ],
      "Self": "http://localhost/api/permission/16342c78-d2ec-4436-a9c3-aaa105cafda4"
    },
    {
      "Id": "b5fee9b8-563a-4d1b-b3b0-4a0cea9cf78e",
      "Key": "/Administration",
      "Name": "Administration",
      "Children": [],
      "Self": "http://localhost/api/permission/b5fee9b8-563a-4d1b-b3b0-4a0cea9cf78e"
    }
  ]
}

Status Code

200 - OK

Resource: Project ( /api/project/{id} )

Represents a project within Enterprise Tester

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Start a background task to delete a project

Required Permissions

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 started successfully.
404 - NotFoundReturned if project was not found.

Example - Delete a project

An example of deleting a package.

Request Parameters

KeyValueDescription
{id}4bb709c2-e0e7-4af3-9f60-a045016a9610GUID Identifier of project to delete.

Response Body

{
  "Complete": false,
  "TotalElements": 10,
  "ProcessedElements": 5,
  "StartedAt": "2011-12-31T11:00:00Z",
  "ProgressInPercent": 0.5,
  "Id": "deleteproject-2acac705-5ab8-4a1b-8586-299d4172b2dc",
  "Message": "Reticulating Splines",
  "Self": "http://localhost/api/backgroundtask/deleteproject-2acac705-5ab8-4a1b-8586-299d4172b2dc"
}

Status Code

200 - OK

GET


Retrieves information about a single project

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if you do not have permission to view this project.

Example - Get Project

Example of fetching a single project (no expansions)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
idEB06E5D8-F774-4B0F-A95C-A911C13527A9Unique GUID identifier of the project

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Name": "Test Project",
  "OrganisationId": "41930a0d-0d44-4a82-a9de-e2c25780130b",
  "OrganisationName": "Acme Inc",
  "ProjectCategoryId": null,
  "ProjectCategoryName": null,
  "Description": null,
  "EstimatedEndDate": null,
  "ManagerId": null,
  "ManagerUserName": null,
  "Slug": "test-project",
  "AutoNumberRequirements": false,
  "AutoNumberScripts": false,
  "Independent": false,
  "RequirementNumberReadOnly": false,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 0,
  "StartDate": null,
  "Expands": [
    "Statuses",
    "Priorities",
    "RequirementTypes",
    "RequirementStatuses",
    "RequirementDifficulties",
    "IncidentTypes",
    "TestTypes",
    "IncidentResolutions",
    "IncidentStatuses",
    "Versions",
    "Components",
    "ExecutionPackages",
    "ScriptPackages",
    "RequirementPackages",
    "TimeTrackingConfiguration"
  ],
  "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Links": [
    {
      "Title": "Project Tickets Search",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/tickets",
      "Rel": "Tickets"
    },
    {
      "Title": "Project Assignees Search",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/assignees",
      "Rel": "Assignees"
    },
    {
      "Title": "Widgets (Editors for entity fields)",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/widgets",
      "Rel": "Widgets"
    }
  ]
}

Status Code

200 - OK

Example - Get Project (with expansions)

Example of fetching a single project (with Priority and Status picklists expanded).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}EB06E5D8-F774-4B0F-A95C-A911C13527A9Unique GUID identifier of the project.
$expandPriorities,StatusesExpand properties to eager fetch.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Name": "Test Project",
  "OrganisationId": "41930a0d-0d44-4a82-a9de-e2c25780130b",
  "OrganisationName": "Acme Inc",
  "ProjectCategoryId": null,
  "ProjectCategoryName": null,
  "Description": null,
  "EstimatedEndDate": null,
  "ManagerId": null,
  "ManagerUserName": null,
  "Slug": "test-project",
  "AutoNumberRequirements": false,
  "AutoNumberScripts": false,
  "Independent": false,
  "RequirementNumberReadOnly": false,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 0,
  "StartDate": null,
  "Expands": [
    "RequirementTypes",
    "RequirementStatuses",
    "RequirementDifficulties",
    "IncidentTypes",
    "TestTypes",
    "IncidentResolutions",
    "IncidentStatuses",
    "Versions",
    "Components",
    "ExecutionPackages",
    "ScriptPackages",
    "RequirementPackages",
    "TimeTrackingConfiguration"
  ],
  "Priorities": [
    {
      "Id": "6b1e46f4-8b59-4dc3-8ed1-0b3b89612e34",
      "Text": "Low",
      "SortOrder": 1,
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/priority/6b1e46f4-8b59-4dc3-8ed1-0b3b89612e34"
    },
    {
      "Id": "5d37d6a1-6b1d-4007-8fcf-2c5296af3740",
      "Text": "High",
      "SortOrder": 2,
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/priority/5d37d6a1-6b1d-4007-8fcf-2c5296af3740"
    }
  ],
  "Statuses": [
    {
      "Id": "753387d7-0a67-45bd-8b96-a58791c283bb",
      "Text": "Draft",
      "SortOrder": 1,
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/status/753387d7-0a67-45bd-8b96-a58791c283bb"
    },
    {
      "Id": "023b39dc-31a3-4bb6-bf01-69da23de5d3f",
      "Text": "Final",
      "SortOrder": 2,
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/status/023b39dc-31a3-4bb6-bf01-69da23de5d3f"
    }
  ],
  "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Links": [
    {
      "Title": "Project Tickets Search",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/tickets",
      "Rel": "Tickets"
    },
    {
      "Title": "Project Assignees Search",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/assignees",
      "Rel": "Assignees"
    },
    {
      "Title": "Widgets (Editors for entity fields)",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/widgets",
      "Rel": "Widgets"
    }
  ]
}

Status Code

200 - OK

PUT


Update an existing project.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the project was updated successfully.
403 - ForbiddenReturned if the user does not have permission to update a project.
404 - NotFoundReturned if the project does not exist.
409 - ConflictReturned if the name for the project is in use (if attempting to rename the project).

Example - Update Project

Example of updating a project

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
idEB06E5D8-F774-4B0F-A95C-A911C13527A9Unique GUID identifier of the project

Request Body

{
  "Name": "New Name",
  "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "ProjectCategoryId": "b8cd5461-24af-4393-b089-c51ed25687fa",
  "Description": "Updated description",
  "EstimatedEndDate": "2012-12-31T11:00:00Z",
  "ManagerId": "1409a902-9d1b-4afb-aa92-082ebe8eb3bf",
  "AutoNumberRequirements": true,
  "AutoNumberScripts": false,
  "Independent": true,
  "RequirementNumberReadOnly": true,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 2,
  "StartDate": "2011-12-31T11:00:00Z"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Name": "New Name",
  "OrganisationId": "41930a0d-0d44-4a82-a9de-e2c25780130b",
  "OrganisationName": "Acme Inc",
  "ProjectCategoryId": "b8cd5461-24af-4393-b089-c51ed25687fa",
  "ProjectCategoryName": "Archived Projects",
  "Description": "Updated description",
  "EstimatedEndDate": "2012-12-31T11:00:00Z",
  "ManagerId": "1409a902-9d1b-4afb-aa92-082ebe8eb3bf",
  "ManagerUserName": "janedoe",
  "Slug": "new-name",
  "AutoNumberRequirements": true,
  "AutoNumberScripts": false,
  "Independent": false,
  "RequirementNumberReadOnly": false,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 2,
  "StartDate": "2011-12-31T11:00:00Z",
  "Expands": [
    "Statuses",
    "Priorities",
    "RequirementTypes",
    "RequirementStatuses",
    "RequirementDifficulties",
    "IncidentTypes",
    "TestTypes",
    "IncidentResolutions",
    "IncidentStatuses",
    "Versions",
    "Components",
    "ExecutionPackages",
    "ScriptPackages",
    "RequirementPackages",
    "TimeTrackingConfiguration"
  ],
  "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
  "Links": [
    {
      "Title": "Project Tickets Search",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/tickets",
      "Rel": "Tickets"
    },
    {
      "Title": "Project Assignees Search",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/assignees",
      "Rel": "Assignees"
    },
    {
      "Title": "Widgets (Editors for entity fields)",
      "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/widgets",
      "Rel": "Widgets"
    }
  ]
}

Status Code

200 - OK

Resource: Project Assignees ( /api/project/{projectId}/assignees )

Allows the searching of available assignees for a project (results are sorted alphabetically).

This resource supports the following methods: GET

Methods

GET


Searches for assignees by partial name match

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the search request was able to be satisfied.
404 - NotFoundReturned if project does not exist.

Example - Search for users

An example of searching for users.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{projectId}E032C596-F299-47CB-B08F-CB2EFFF60E27ID of the project to find assignable users for
queryjoThe partial username, firstname or lastname to search for
$skip20Number of items to skip (start result number)
$top10Number of search results to return
$inlinecountallpagesInclude or supress inline counts
$expandDisplayNameAllows expansion of additional user properties

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 20,
  "Top": 10,
  "Total": 1,
  "Items": [
    {
      "Id": "3464e9da-f1b7-49aa-87db-7e1eebfd17a5",
      "UserName": "joeb",
      "Email": "joeb@unknown.net",
      "FirstName": "Joe",
      "LastName": "Bloggs",
      "Phone": "(09)-555-999",
      "LastLogIn": null,
      "Enabled": true,
      "IsExternal": false,
      "DisplayName": "Joe Bloggs (joeb)",
      "Self": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5",
      "Links": [
        {
          "Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/password",
          "Rel": "ChangePassword"
        },
        {
          "Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/permissions/global",
          "Rel": "GlobalPermissions"
        },
        {
          "Title": "Group Memberships",
          "Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/groups",
          "Rel": "Groups"
        },
        {
          "Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/notifications",
          "Rel": "Notifications"
        },
        {
          "Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/permissions/projects",
          "Rel": "ProjectPermissions"
        },
        {
          "Href": "http://localhost/api/user/3464e9da-f1b7-49aa-87db-7e1eebfd17a5/mailmessages",
          "Rel": "MailMessages"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/project/E032C596-F299-47CB-B08F-CB2EFFF60E27/assignees?query=jo&$skip=20&$top=10&$inlinecount=allpages",
  "Links": [
    {
      "Href": "http://localhost/api/project/E032C596-F299-47CB-B08F-CB2EFFF60E27/assignees?query=jo&$skip=10&$top=10&$inlinecount=allpages",
      "Rel": "prev"
    },
    {
      "Href": "http://localhost/api/project/E032C596-F299-47CB-B08F-CB2EFFF60E27/assignees?query=jo&$skip=0&$top=10&$inlinecount=allpages",
      "Rel": "first"
    }
  ]
}

Status Code

200 - OK

Resource: Project Categories ( /api/projectcategories )

Project Categories (collection) resource

Root Relation: ProjectCategories

This resource supports the following methods: GET, POST

Methods

GET


Retrieves a list of all project categories.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Get all project categories

Retrieves a list of all project categories.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
      "Name": "Active",
      "OrderNumber": 0,
      "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
      "OrganisationName": "Acme Inc",
      "ParentId": null,
      "ParentName": null,
      "HasChildren": true,
      "HasProjects": false,
      "HasParent": false,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/dc8b3352-05cf-4b54-868b-a1f6c3cc73ba"
    },
    {
      "Id": "092c1c83-cfe7-4075-aea8-4dc445f8d87d",
      "Name": "Mobile",
      "OrderNumber": 0,
      "OrganisationId": null,
      "OrganisationName": null,
      "ParentId": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
      "ParentName": "Active",
      "HasChildren": false,
      "HasProjects": false,
      "HasParent": true,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/092c1c83-cfe7-4075-aea8-4dc445f8d87d"
    },
    {
      "Id": "4b538f8f-994b-4a82-8874-22a16586eebf",
      "Name": "Archived",
      "OrderNumber": 1,
      "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
      "OrganisationName": "Acme Inc",
      "ParentId": null,
      "ParentName": null,
      "HasChildren": false,
      "HasProjects": false,
      "HasParent": false,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/4b538f8f-994b-4a82-8874-22a16586eebf"
    }
  ]
}

Status Code

200 - OK

Example - Retrieves filtered set of project categories.

Retrieves a list of project categories filtered by name.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterName eq 'Archive'Retrieves a list of all project categories with the name 'Archive'.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "4b538f8f-994b-4a82-8874-22a16586eebf",
      "Name": "Archived",
      "OrderNumber": 1,
      "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
      "OrganisationName": "Acme Inc",
      "ParentId": null,
      "ParentName": null,
      "HasChildren": false,
      "HasProjects": false,
      "HasParent": false,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/4b538f8f-994b-4a82-8874-22a16586eebf"
    }
  ]
}

Status Code

200 - OK

POST


Create a new project category.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the project category was created successfully.
403 - ForbiddenReturned if the project category could not be created (due to lack of permissions or an invalid json request).
409 - ConflictReturned if the project category name is already in use.

Example - Create a new project category (for organisation).

Create a new project category directly underneath an organisation (note: if OrganisationId and ParentId are both omitted, then default organisation will be used).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "Name": "Sandbox",
  "OrderNumber": 3
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/projectcategory/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "Sandbox",
  "OrderNumber": 3,
  "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
  "OrganisationName": "Acme Inc",
  "ParentId": null,
  "ParentName": null,
  "HasChildren": false,
  "HasProjects": false,
  "HasParent": false,
  "Self": "http://localhost/api/projectcategory/4bb709c2-e0e7-4af3-9f60-a045016a9610"
}

Status Code

201 - Created

Example - Create a new project category (for parent).

Create a new project category underneath another project category.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

{
  "Name": "Desktop",
  "ParentId": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/projectcategory/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "Desktop",
  "OrderNumber": 0,
  "OrganisationId": null,
  "OrganisationName": null,
  "ParentId": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
  "ParentName": "Active",
  "HasChildren": false,
  "HasProjects": false,
  "HasParent": true,
  "Self": "http://localhost/api/projectcategory/4bb709c2-e0e7-4af3-9f60-a045016a9610"
}

Status Code

201 - Created

Resource: Project Category ( /api/projectcategory/{id} )

Project Category resource

This resource supports the following methods: DELETE, GET, PUT

Methods

DELETE


Delete a project category (removing a project category does not remove the projects beneath it, these will instead be moved directly beneath the organisation).

Required Permissions

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
200 - OKProject category deleted successfully.
403 - ForbiddenReturned if project category could not be deleted (normally due to lack of permissions).
404 - NotFoundReturned if project category does not exist.

Example - Delete a project category.

Delete a project category.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}dc8b3352-05cf-4b54-868b-a1f6c3cc73baUnique identifier of the project category.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET


Retrieves a project category by its unique identifier.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if project category does not exist.

Example - Get a project category by the unique identifier.

Retrieve a project category by its unique identifier

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}DC8B3352-05CF-4B54-868B-A1F6C3CC73BAThe unique identifier of the project category.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
  "Name": "Active",
  "OrderNumber": 0,
  "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
  "OrganisationName": "Acme Inc",
  "ParentId": null,
  "ParentName": null,
  "HasChildren": true,
  "HasProjects": false,
  "HasParent": false,
  "Self": "http://localhost/api/projectcategory/dc8b3352-05cf-4b54-868b-a1f6c3cc73ba"
}

Status Code

200 - OK

PUT


Update a project category.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKUpdate a project category.
403 - ForbiddenReturned if project category could not be updated (due to lack of permissions or an invalid json request).
404 - NotFoundReturned if project category does not exist.
409 - ConflictReturned if project category name is already in use.

Example - Update an existing project category (rename).

Updates the name of a project category.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}dc8b3352-05cf-4b54-868b-a1f6c3cc73baUnique identifier of the project category.

Request Body

{
  "Name": "In Flight"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
  "Name": "In Flight",
  "OrderNumber": 0,
  "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
  "OrganisationName": "Acme Inc",
  "ParentId": null,
  "ParentName": null,
  "HasChildren": true,
  "HasProjects": false,
  "HasParent": false,
  "Self": "http://localhost/api/projectcategory/dc8b3352-05cf-4b54-868b-a1f6c3cc73ba"
}

Status Code

200 - OK

Example - Update an existing project category (move to a new parent).

Moves a project category to a new parent.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}092c1c83-cfe7-4075-aea8-4dc445f8d87dUnique identifier of the project category.

Request Body

{
  "ParentId": "4b538f8f-994b-4a82-8874-22a16586eebf"
}

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "092c1c83-cfe7-4075-aea8-4dc445f8d87d",
  "Name": "Mobile",
  "OrderNumber": 0,
  "OrganisationId": null,
  "OrganisationName": null,
  "ParentId": "4b538f8f-994b-4a82-8874-22a16586eebf",
  "ParentName": "Archived",
  "HasChildren": false,
  "HasProjects": false,
  "HasParent": true,
  "Self": "http://localhost/api/projectcategory/092c1c83-cfe7-4075-aea8-4dc445f8d87d"
}

Status Code

200 - OK

Resource: Project Category Children ( /api/projectcategory/{id}/children )

Project Category Children (collection) resource

This resource supports the following methods: GET

Methods

GET


Retrieves a list of all child project categories for a project category.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request is completed successfully.
404 - NotFoundReturned if project category does not exist.

Example - Retrieves all children of a project category.

Retrieves all the child categories of a project category.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}dc8b3352-05cf-4b54-868b-a1f6c3cc73baUnique identifier of the project category.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "092c1c83-cfe7-4075-aea8-4dc445f8d87d",
      "Name": "Mobile",
      "OrderNumber": 0,
      "OrganisationId": null,
      "OrganisationName": null,
      "ParentId": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
      "ParentName": "Active",
      "HasChildren": false,
      "HasProjects": false,
      "HasParent": true,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/092c1c83-cfe7-4075-aea8-4dc445f8d87d"
    },
    {
      "Id": "c0b6196a-59d1-46e4-a007-cb7c69562394",
      "Name": "Desktop",
      "OrderNumber": 1,
      "OrganisationId": null,
      "OrganisationName": null,
      "ParentId": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
      "ParentName": "Active",
      "HasChildren": false,
      "HasProjects": false,
      "HasParent": true,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/c0b6196a-59d1-46e4-a007-cb7c69562394"
    }
  ]
}

Status Code

200 - OK

Resource: Project Group Permissions ( /api/group/{groupId}/permissions/project/{projectId} )

Project Group Permissions resource - allows the retrieval of the collection of permissions directly associated with a group for a project, or updating the permissions associated with a project group.

This resource supports the following methods: GET, PUT

Methods

GET


Retrieves the project permissions for this group

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the group does not exist.

Example - Retrieve Permissions

Retrieve the permissions assigned to this group for selected project.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{groupId}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the group to retrieve permissions for
{projectId}9ee7ac7b-1fa9-4af6-91f2-cc59408b84d7Unique ID of the project to retrieve permissions for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

PUT


Sets the project permissions for this group

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if one or more permissions could not be resolved.
404 - NotFoundReturned if the group or project does not exist.

Example - Set Permissions (by Permission ID)

Set the permissions to grant to the group for this project (using the ID for each permission)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{groupId}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the group to set project permissions for
{projectId}9ee7ac7b-1fa9-4af6-91f2-cc59408b84d7Unique ID of the project to set group permissions for

Request Body

[
  {
    "Key": null,
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22"
  },
  {
    "Key": null,
    "Id": "fad12035-4937-401a-881a-ea340050218e"
  }
]

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

Example - Set Permissions (by Key)

Set the permissions to grant to the group for this project (using the unique Key for each permission)

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{groupId}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the group to set project permissions for
{projectId}9ee7ac7b-1fa9-4af6-91f2-cc59408b84d7Unique ID of the project to set group permissions for

Request Body

[
  {
    "Key": "/Administration",
    "Id": null
  },
  {
    "Key": "/Resources",
    "Id": null
  }
]

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

Resource: Project Picklist ( /api/project/{projectId}/picklist/{type} )

Used to retrieve the picklist values associated with a project

This resource supports the following methods: GET

Methods

GET


Retrieve picklist values specific to a project.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

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
200 - OKReturned if the picklist values were retrieved successfully.
403 - ForbiddenReturned if the user does not have permission to view picklist values for this project.
404 - NotFoundReturned if the project does not exist.

Example - Retrieve all picklist values

Retrieve all picklist value for the picklist 'Priority'.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{projectId}bc692c60-99b2-4df3-8cf8-74f4ac770b16Unique ID of the project related to the picklist values.
{type}PriorityThe picklist type e.g. Priority, RequirementType, RequirementStatus, RequirementDifficulty, IncidentResolution etc.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "2fe983c7-bc0d-430f-83f2-9a97863e4891",
      "Text": "High",
      "SortOrder": 0,
      "Self": "http://localhost/api/project/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/2fe983c7-bc0d-430f-83f2-9a97863e4891"
    },
    {
      "Id": "fb82918b-cb0e-4c38-b994-bc35f469d020",
      "Text": "Medium",
      "SortOrder": 1,
      "Self": "http://localhost/api/project/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/fb82918b-cb0e-4c38-b994-bc35f469d020"
    },
    {
      "Id": "b6a3cb4d-638b-4803-9cf5-bc9830e29835",
      "Text": "Low",
      "SortOrder": 2,
      "Self": "http://localhost/api/project/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/b6a3cb4d-638b-4803-9cf5-bc9830e29835"
    }
  ],
  "Self": "http://localhost/api/api/project/BC692C60-99B2-4DF3-8CF8-74F4AC770B16/picklistsearch/Priority"
}

Status Code

200 - OK

Resource: Project Picklist Search ( /api/project/{projectId}/picklistsearch/{type} )

Allows the searching of picklist values for an project by partial name match.

This resource supports the following methods: GET, POST

Methods

GET


Searches for picklist values by partial name match

Required Permissions

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
200 - OKReturned if the picklist values were retrieved successfully.
403 - ForbiddenReturned if the user does not have permission to view picklist values for this project.
404 - NotFoundReturned if the project does not exist.

Example - Retrieve all picklist values

Retrieve all picklist values

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{projectId}bc692c60-99b2-4df3-8cf8-74f4ac770b16Unique ID of the project related to the picklist values.
{type}PriorityThe picklist type e.g. Priority, RequirementType, RequirementStatus, RequirementDifficulty, IncidentResolution etc.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "2fe983c7-bc0d-430f-83f2-9a97863e4891",
      "Text": "High",
      "SortOrder": 0,
      "Self": "http://localhost/api/project/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/2fe983c7-bc0d-430f-83f2-9a97863e4891"
    }
  ],
  "Self": "http://localhost/api/api/project/BC692C60-99B2-4DF3-8CF8-74F4AC770B16/picklistsearch/Priority?query=H"
}

Status Code

200 - OK

POST


Searches for picklist values by partial name match

Required Permissions

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
200 - OKReturned if the picklist values were retrieved successfully.
403 - ForbiddenReturned if the user does not have permission to view picklist values for this project.
404 - NotFoundReturned if the project does not exist.

Example - Retrieve all picklist values

Retrieve all picklist values

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{projectId}bc692c60-99b2-4df3-8cf8-74f4ac770b16Unique ID of the project related to the picklist values.
{type}PriorityThe picklist type e.g. Priority, RequirementType, RequirementStatus, RequirementDifficulty, IncidentResolution etc.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "2fe983c7-bc0d-430f-83f2-9a97863e4891",
      "Text": "High",
      "SortOrder": 0,
      "Self": "http://localhost/api/project/bc692c60-99b2-4df3-8cf8-74f4ac770b16/priority/2fe983c7-bc0d-430f-83f2-9a97863e4891"
    }
  ],
  "Self": "http://localhost/api/api/project/BC692C60-99B2-4DF3-8CF8-74F4AC770B16/picklistsearch/Priority"
}

Status Code

200 - OK

Resource: Project Templates ( /api/projecttemplates )

Project templates that can be used when creating a new project to pre-populate the project with data.

Root Relation: ProjectTemplates

This resource supports the following methods: GET

Methods

GET


Retrieves all (or a subset) of project templates that are visible to the user.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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
200 - OKReturned if the request was completed successfully.

Example - Get all Project templates

An example of retrieving all project templates.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
    "Title": "Agile Template",
    "Expands": [],
    "Self": "http://localhost/api/projecttemplate/eb06e5d8-f774-4b0f-a95c-a911c13527a9"
  },
  {
    "Id": "00000000-0000-0000-0000-000000000000",
    "Title": "Empty Project",
    "Expands": [],
    "Self": "http://localhost/api/projecttemplate/00000000-0000-0000-0000-000000000000"
  }
]

Status Code

200 - OK

Example - Get project templates filtered by title

Example of fetching a set of project templates by name, by using the ODATA $filter query parameter.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterTitle eq 'Agile Template'The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Title%20eq%20'Agile Template'.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
    "Title": "Agile Template",
    "Expands": [],
    "Self": "http://localhost/api/projecttemplate/eb06e5d8-f774-4b0f-a95c-a911c13527a9"
  }
]

Status Code

200 - OK

Resource: Project Tickets ( /api/project/{projectId}/tickets )

Allows the searching of tickets in external systems

This resource supports the following methods: GET

Methods

GET


Retrieves tickets for a project via a query

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Search tickets for items matching query

An example of fetching tickets matching a text search.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{projectId}D2FA3402-30FD-4714-BB39-FAA30748BC14Unique ID of Project to find tickets for
qtestText to search for in ticket

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "Key": "TST-4629",
      "Summary": "Test windows title clips text on bottom",
      "Url": "https://mycompany.atlassian.net/browse/TST-4629",
      "Id": "18759",
      "Type": "Bug",
      "ExternalSystemId": "c63e805c-e5d3-4919-9d10-a0a500e0754a",
      "ExternalSystemName": "testing",
      "IncidentId": null,
      "Status": "Open",
      "InternalKey": null,
      "Self": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a/ticket/18759",
      "Links": [
        {
          "Href": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a/ticket/18759/link",
          "Rel": "StartCreateIncident"
        },
        {
          "Href": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a",
          "Rel": "ExternalSystemLink"
        }
      ]
    },
    {
      "Key": "TST-2222",
      "Summary": "Re-run selenium tests",
      "Url": "https://mycompany.atlassian.net/browse/TST-2222",
      "Id": "12123",
      "Type": "Task",
      "ExternalSystemId": "c63e805c-e5d3-4919-9d10-a0a500e0754a",
      "ExternalSystemName": "testing",
      "IncidentId": null,
      "Status": "In Progress",
      "InternalKey": null,
      "Self": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a/ticket/12123",
      "Links": [
        {
          "Href": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a/ticket/12123/link",
          "Rel": "StartCreateIncident"
        },
        {
          "Href": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a",
          "Rel": "ExternalSystemLink"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/project/D2FA3402-30FD-4714-BB39-FAA30748BC14/tickets?q=test"
}

Status Code

200 - OK

Example - Search tickets for items matching query (with different number of max results)

An example of fetching tickets matching a text search, with a configured maximum number of results.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{projectId}D2FA3402-30FD-4714-BB39-FAA30748BC14Unique ID of Project to find tickets for
qtestText to search for in ticket
$top1Maxmimum number of tickets to return

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 1,
  "Total": 1,
  "Items": [
    {
      "Key": "TST-4629",
      "Summary": "Test windows title clips text on bottom",
      "Url": "https://mycompany.atlassian.net/browse/TST-4629",
      "Id": "18759",
      "Type": "Bug",
      "ExternalSystemId": "c63e805c-e5d3-4919-9d10-a0a500e0754a",
      "ExternalSystemName": "testing",
      "IncidentId": null,
      "Status": "Open",
      "InternalKey": null,
      "Self": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a/ticket/18759",
      "Links": [
        {
          "Href": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a/ticket/18759/link",
          "Rel": "StartCreateIncident"
        },
        {
          "Href": "http://localhost/api/externalsystemlink/c63e805c-e5d3-4919-9d10-a0a500e0754a",
          "Rel": "ExternalSystemLink"
        }
      ]
    }
  ],
  "Self": "http://localhost/api/api/project/D2FA3402-30FD-4714-BB39-FAA30748BC14/tickets?q=test&$top=1"
}

Status Code

200 - OK

Resource: Project User Permissions ( /api/user/{userId}/permissions/project/{projectId} )

Project User Permissions resource - allows the retrieval of the collection of permissions directly associated with a user for a project, or updating the permissions associated with a project user.

This resource supports the following methods: GET, PUT

Methods

GET


Retrieves the project permissions for this user

Required Permissions

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
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if the user does not exist.

Example - Retrieve Permissions

Retrieve the permissions assigned to this user for selected project.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the user to retrieve permissions for
{projectId}9ee7ac7b-1fa9-4af6-91f2-cc59408b84d7Unique ID of the project to retrieve permissions for

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

PUT


Sets the project permissions for this user

Required Permissions

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
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned if one or more permissions could not be resolved.
404 - NotFoundReturned if the user or project does not exist.

Example - Set Permissions (by Permission ID)

Set the permissions to grant to the user for this project (using the ID for each permission).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the user to set project permissions for
{projectId}9ee7ac7b-1fa9-4af6-91f2-cc59408b84d7Unique ID of the project to set user permissions for

Request Body

[
  {
    "Key": null,
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22"
  },
  {
    "Key": null,
    "Id": "fad12035-4937-401a-881a-ea340050218e"
  }
]

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

Example - Set Permissions (by Key)

Set the permissions to grant to the user for this project (using the unique Key for each permission).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
{userId}3a31a68a-9e51-4d87-91bb-aca0fa5c1fe9Unique ID of the user to set project permissions for
{projectId}9ee7ac7b-1fa9-4af6-91f2-cc59408b84d7Unique ID of the project to set user permissions for

Request Body

[
  {
    "Key": "/Administration",
    "Id": null
  },
  {
    "Key": "/Resources",
    "Id": null
  }
]

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

[
  {
    "Id": "e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
    "Key": "/Administration",
    "Links": [
      {
        "Href": "http://localhost/api/permission/e6a7d6d3-6b16-4e94-a768-54bdd8bb3b22",
        "Rel": "Permission"
      }
    ]
  },
  {
    "Id": "fad12035-4937-401a-881a-ea340050218e",
    "Key": "/Resources",
    "Links": [
      {
        "Href": "http://localhost/api/permission/fad12035-4937-401a-881a-ea340050218e",
        "Rel": "Permission"
      }
    ]
  }
]

Status Code

200 - OK

Resource: Projects ( /api/projects )

Projects collection resource, allowing the search and retrieval of all visible projects.

Root Relation: Projects

This resource supports the following methods: GET, POST

Methods

GET


Retrieves all (or a subset) of projects that are visible to the user.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
200 - OKReturned if the request was completed successfully.

Example - Get All Projects

An example of Retrieving all projects.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
      "Name": "Project ABC",
      "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
      "OrganisationName": "Acme Inc.",
      "ProjectCategoryId": null,
      "ProjectCategoryName": null,
      "Description": null,
      "EstimatedEndDate": null,
      "ManagerId": null,
      "ManagerUserName": null,
      "Slug": "abc",
      "AutoNumberRequirements": false,
      "AutoNumberScripts": false,
      "Independent": false,
      "RequirementNumberReadOnly": false,
      "ScriptNumberReadOnly": false,
      "OrderNumber": 0,
      "StartDate": null,
      "Expands": [
        "Statuses",
        "Priorities",
        "RequirementTypes",
        "RequirementStatuses",
        "RequirementDifficulties",
        "IncidentTypes",
        "TestTypes",
        "IncidentResolutions",
        "IncidentStatuses",
        "Versions",
        "Components",
        "ExecutionPackages",
        "ScriptPackages",
        "RequirementPackages",
        "TimeTrackingConfiguration"
      ],
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
      "Links": [
        {
          "Title": "Project Tickets Search",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/tickets",
          "Rel": "Tickets"
        },
        {
          "Title": "Project Assignees Search",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/assignees",
          "Rel": "Assignees"
        },
        {
          "Title": "Widgets (Editors for entity fields)",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/widgets",
          "Rel": "Widgets"
        }
      ]
    },
    {
      "Id": "cd69b4f5-507d-4735-b0af-8493c91b43a8",
      "Name": "Project XYZ",
      "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
      "OrganisationName": "Acme Inc.",
      "ProjectCategoryId": null,
      "ProjectCategoryName": null,
      "Description": null,
      "EstimatedEndDate": null,
      "ManagerId": null,
      "ManagerUserName": null,
      "Slug": "xyz",
      "AutoNumberRequirements": false,
      "AutoNumberScripts": false,
      "Independent": false,
      "RequirementNumberReadOnly": false,
      "ScriptNumberReadOnly": false,
      "OrderNumber": 0,
      "StartDate": null,
      "Expands": [
        "Statuses",
        "Priorities",
        "RequirementTypes",
        "RequirementStatuses",
        "RequirementDifficulties",
        "IncidentTypes",
        "TestTypes",
        "IncidentResolutions",
        "IncidentStatuses",
        "Versions",
        "Components",
        "ExecutionPackages",
        "ScriptPackages",
        "RequirementPackages",
        "TimeTrackingConfiguration"
      ],
      "Self": "http://localhost/api/project/cd69b4f5-507d-4735-b0af-8493c91b43a8",
      "Links": [
        {
          "Title": "Project Tickets Search",
          "Href": "http://localhost/api/project/cd69b4f5-507d-4735-b0af-8493c91b43a8/tickets",
          "Rel": "Tickets"
        },
        {
          "Title": "Project Assignees Search",
          "Href": "http://localhost/api/project/cd69b4f5-507d-4735-b0af-8493c91b43a8/assignees",
          "Rel": "Assignees"
        },
        {
          "Title": "Widgets (Editors for entity fields)",
          "Href": "http://localhost/api/project/cd69b4f5-507d-4735-b0af-8493c91b43a8/widgets",
          "Rel": "Widgets"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Example - Get Projects filtered by name

An example of retrieving a set of projects by name, by using the ODATA $filter query parameter.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterName eq 'Project ABC'The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Name%20eq%20'Project ABC'

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
      "Name": "Project ABC",
      "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
      "OrganisationName": "Acme Inc.",
      "ProjectCategoryId": null,
      "ProjectCategoryName": null,
      "Description": null,
      "EstimatedEndDate": null,
      "ManagerId": null,
      "ManagerUserName": null,
      "Slug": "abc",
      "AutoNumberRequirements": false,
      "AutoNumberScripts": false,
      "Independent": false,
      "RequirementNumberReadOnly": false,
      "ScriptNumberReadOnly": false,
      "OrderNumber": 0,
      "StartDate": null,
      "Expands": [
        "Statuses",
        "Priorities",
        "RequirementTypes",
        "RequirementStatuses",
        "RequirementDifficulties",
        "IncidentTypes",
        "TestTypes",
        "IncidentResolutions",
        "IncidentStatuses",
        "Versions",
        "Components",
        "ExecutionPackages",
        "ScriptPackages",
        "RequirementPackages",
        "TimeTrackingConfiguration"
      ],
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
      "Links": [
        {
          "Title": "Project Tickets Search",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/tickets",
          "Rel": "Tickets"
        },
        {
          "Title": "Project Assignees Search",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/assignees",
          "Rel": "Assignees"
        },
        {
          "Title": "Widgets (Editors for entity fields)",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/widgets",
          "Rel": "Widgets"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST


Create a new project.

Required Permissions

Supported Expansions

For more details on expansions, please see the Expand help topic.

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
201 - CreatedReturned if the new project was created successfully.
403 - ForbiddenReturned if the user does not have permission to create a project.
409 - ConflictReturned if the projects name is already in use.

Example - Create a project

Example of creating a new project.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{
  "Name": "My New Project",
  "ProjectCategoryId": "28f16438-8dfa-49cc-8db3-18aa1803cb86",
  "Description": "My new ET project",
  "EstimatedEndDate": "2012-12-31T11:00:00Z",
  "ManagerId": "83116d87-fff5-408b-8cdd-5491d17a9a26",
  "AutoNumberRequirements": true,
  "AutoNumberScripts": true,
  "Independent": false,
  "RequirementNumberReadOnly": true,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 1,
  "StartDate": "2011-12-31T11:00:00Z",
  "TimeTrackingConfiguration": {
    "HoursPerDay": 24,
    "DaysPerWeek": 7
  }
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "My New Project",
  "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
  "OrganisationName": "Acme Inc.",
  "ProjectCategoryId": "28f16438-8dfa-49cc-8db3-18aa1803cb86",
  "ProjectCategoryName": "Current Projects",
  "Description": "My new ET project",
  "EstimatedEndDate": "2012-12-31T11:00:00Z",
  "ManagerId": "83116d87-fff5-408b-8cdd-5491d17a9a26",
  "ManagerUserName": "joeb",
  "Slug": "my-new-project",
  "AutoNumberRequirements": true,
  "AutoNumberScripts": true,
  "Independent": false,
  "RequirementNumberReadOnly": false,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 1,
  "StartDate": "2011-12-31T11:00:00Z",
  "Self": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Title": "Project Tickets Search",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/tickets",
      "Rel": "Tickets"
    },
    {
      "Title": "Project Assignees Search",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/assignees",
      "Rel": "Assignees"
    },
    {
      "Title": "Widgets (Editors for entity fields)",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/widgets",
      "Rel": "Widgets"
    }
  ]
}

Status Code

201 - Created

Example - Create a project using template

An example of creating a new project using a template (using the Id for the template retrieved from the list of project templates at /api/projecttemplates) - we leave all other configuration to be their default values.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Body

{ 
    "Name": "My New Project",
    "TemplateId": "C3A156A4-5CE0-4773-938A-9C6EADC030FD"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "My New Project",
  "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
  "OrganisationName": "Acme Inc.",
  "ProjectCategoryId": null,
  "ProjectCategoryName": null,
  "Description": null,
  "EstimatedEndDate": null,
  "ManagerId": null,
  "ManagerUserName": null,
  "Slug": "my-new-project",
  "AutoNumberRequirements": false,
  "AutoNumberScripts": false,
  "Independent": false,
  "RequirementNumberReadOnly": false,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 0,
  "StartDate": null,
  "Self": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Title": "Project Tickets Search",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/tickets",
      "Rel": "Tickets"
    },
    {
      "Title": "Project Assignees