Issue Tracking System Instance API
Issue Tracking Systems can be accessed and modified through this API using four services: GET, POST, PUT, and PATCH. These four services allow for the retrieval, creation, complete update, and partial update of Issue Tracking Systems. You can find more information about the REST API functions on the /wiki/spaces/FLEX/pages/392986625page.
Authentication - Use Basic Authentication for this API.
JIRA
Property Name | Type | Required | Description | Example Property Value |
---|---|---|---|---|
JIRA_USER_NAME | String | Yes | User name to login into the JIRA server | username |
JIRA_PASSWORD | String | Yes | API token or password to login into the JIRA server. Jira Documentation contains more information on generating API tokens. | password |
JIRA_PORT | Integer | Yes | Port to access the JIRA system | 1234 |
JIRA_TICKET_REST_PATTERN | String | Yes | Pattern to update/retrieve information on a given JIRA ticket on the JIRA server | /rest/api/2/issue/{JIRA_ISSUE} |
JIRA_TICKET_URL_PATTERN | String | Yes | Pattern to link to a given JIRA ticket on the JIRA server | /browse/{JIRA_ISSUE} |
JIRA_URL | String | Yes | URL to the JIRA system | http://myjira.atlassian.net |
GET
There are two implementations of GET. One will find an Issue Tracking System with the given Id and return the JSON representation of the Issue Tracking System. The other will find a list of Issue Tracking Systems matching the parameters supplied to it.
GET by ID
This GET service will find an Issue Tracking System with the given Id and return the JSON representation of the object.
API URL
http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance/{Id}
Request
Parameter | Required | Type | Description |
---|---|---|---|
Id | Yes | URL | URL parameter for the Id which is used to find and return an issue tracking system |
Response
Attributes | Type | Required | Description |
---|---|---|---|
instanceId | Integer | No | Primary ID of the Issue Tracking System, created when first making an Issue Tracking System. |
instanceCode | String | Yes | The code of the Issue Tracking System |
instanceName | String | Yes | The name of the Issue Tracking System |
issueTrackingSystemId | Integer | Yes | The ID of the type of Issue Tracking System |
description | String | No | The description of the Issue Tracking System |
isActive | Boolean | No | Whether or not this Issue Tracking System is active. |
properties | List<PropertyValue> | No | The properties associated with the type of Issue Tracking System |
Each JSON ITS instance object contains a list of property value. The property value object has these attributes.
Attributes | Type | Description |
---|---|---|
propertyName | String | This is the name of the property |
propertyValue | String | This is the value of the property |
credentialId | Long | Id of the credential associated with the property. Applicable only for encrypted properties |
Response Codes
HTTP Code | Description |
---|---|
200 | Issue Tracking System instance was found and returned |
400 | Bad request |
401 | Authentication failure |
403 | Authorization failure (no access to resource) |
404 | Issue Tracking System instance not found |
500 | Unexpected internal server error |
GET by Query Parameters
This GET service will return a list of Issue Tracking Systems in the form of JSON objects based on the query parameters code, name, and issue tracking system type. Issue Tracking Systems are only returned if they match ALL of the specified query parameters. If no query parameters are given this request will return the entire list of Issue Tracking Systems.
API URL
http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance?
Append the following character sequences to the above URL to specify Query parameters.
Use '&' between successive query parameters:
instanceCode={instanceCode}
instanceName={instanceName}
itsName={itsName}
Examples:
To specify the code parameter only:
http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance?instanceCode={instanceCode}
To specify the code and name parameters:
http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance?instanceCode={instanceCode}&instanceName={instanceName}
To specify the issue tracking system name only:
http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance?itsName={itsName}
The query parameters are not case sensitive. Searching by instanceName=NAME is the same as searching by instanceName=name.
Request
Parameter | Required | Type | Description |
---|---|---|---|
instanceCode | No | Query - String | This is a URL query parameter for the instance code which is used to search the issue tracking systems. Equals ignore case search |
instanceName | No | Query - String | This is a URL query parameter for the instance name which is used to search the issue tracking systems. Contains ignore case search |
itsName | No | Query - String | This is a URL query parameter for the issue tracking system name which is used to search the issue tracking systems. Equals ignore case search |
Response
Attributes | Type | Required | Description |
---|---|---|---|
instanceId | Integer | No | Primary ID of the Issue Tracking System, created when first making an Issue Tracking System. |
instanceCode | String | Yes | The code of the Issue Tracking System |
instanceName | String | Yes | The name of the Issue Tracking System |
issueTrackingSystemId | Integer | Yes | The ID of the type of Issue Tracking System |
description | String | No | The description of the Issue Tracking System |
isActive | Boolean | No | Whether or not this Issue Tracking System is active. |
properties | List<PropertyValue> | No | The properties associated with the type of Issue Tracking System |
Each JSON ITS instance object contains a list of property value. The property value object has these attributes.
Attributes | Type | Description |
---|---|---|
propertyName | String | This is the name of the property |
propertyValue | String | This is the value of the property |
credentialId | Long | Id of the credential associated with the property. Applicable only for encrypted properties |
Response Codes
HTTP Code | Description |
---|---|
200 | Search successful and results returned |
400 | Bad request |
401 | Authentication failure |
403 | Authorization failure (no access to resource) |
500 | Unexpected internal server error |
Example
Output when the Group Code was made "Group" through http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance?itsName=Jira
[ { "instanceId": 11101, "instanceCode": "ITS", "instanceName": "ITS Name", "issueTrackingSystemId": 1, "description": "ITS example", "isActive": true, "properties": [ { "propertyName": "JIRA_PASSWORD", "propertyValue": "*****", "credentialId": 45845 }, { "propertyName": "JIRA_PORT", "propertyValue": "1234", "credentialId": null }, { "propertyName": "JIRA_TICKET_REST_PATTERN", "propertyValue": "/rest/api/2/issue/{JIRA_ISSUE}", "credentialId": null }, { "propertyName": "JIRA_TICKET_URL_PATTERN", "propertyValue": "/browse/{JIRA_ISSUE}", "credentialId": null }, { "propertyName": "JIRA_URL", "propertyValue": "http://myjira.atlassian.net", "credentialId": null }, { "propertyName": "JIRA_USER_NAME", "propertyValue": "username", "credentialId": null } ] }, { "instanceId": 11105, "instanceCode": "ITS2", "instanceName": "ITS 2 Name", "issueTrackingSystemId": 1, "description": "ITS example 2", "isActive": true, "properties": [ { "propertyName": "JIRA_PASSWORD", "propertyValue": "*****", "credentialId": 96258 }, { "propertyName": "JIRA_PORT", "propertyValue": "2345", "credentialId": null }, { "propertyName": "JIRA_TICKET_REST_PATTERN", "propertyValue": "/rest/api/2/issue/{JIRA_ISSUE}", "credentialId": null }, { "propertyName": "JIRA_TICKET_URL_PATTERN", "propertyValue": "/browse/{JIRA_ISSUE}", "credentialId": null }, { "propertyName": "JIRA_URL", "propertyValue": "http://myjira.atlassian.net", "credentialId": null }, { "propertyName": "JIRA_USER_NAME", "propertyValue": "admin", "credentialId": null } ] } ]
POST
The POST service will create a new issue tracking system with the same attributes as the given JSON object. It returns the JSON representation of the issue tracking system that was just created with an updated ID attribute.
API URL
http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance
Request
Attributes | Type | Required | Description |
---|---|---|---|
instanceCode | String | Yes | The code of the Issue Tracking System. |
instanceName | String | Yes | The name of the Issue Tracking System. |
issueTrackingSystemId | Integer | Yes | The ID of the type of Issue Tracking System. |
description | String | No | The description of the Issue Tracking System. |
isActive | Boolean | Yes | Whether or not this Issue Tracking System is active. Defaults to true. |
properties | List<PropertyValue> | Depends | The properties associated with the type of Issue Tracking System: requirements depend on the Issue Tracking System selected. See more details about a PropertyValue object below. |
PropertyValue
Attributes | Type | Description |
---|---|---|
propertyName | String | This is the name of the property |
propertyValue | String | This is the value of the property |
credentialId | Long | Id of the credential associated with the property. Applicable only for encrypted properties |
Response
Attributes | Type | Required | Description |
---|---|---|---|
instanceId | Integer | No | Primary ID of the Issue Tracking System, created when first making an Issue Tracking System. |
instanceCode | String | Yes | The code of the Issue Tracking System |
instanceName | String | Yes | The name of the Issue Tracking System |
issueTrackingSystemId | Integer | Yes | The ID of the type of Issue Tracking System |
description | String | No | The description of the Issue Tracking System |
isActive | Boolean | No | Whether or not this Issue Tracking System is active. |
properties | List<PropertyValue> | No | The properties associated with the type of Issue Tracking System |
Each JSON ITS instance object contains a list of property value. The property value object has these attributes.
Attributes | Type | Description |
---|---|---|
propertyName | String | This is the name of the property |
propertyValue | String | This is the value of the property |
credentialId | Long | Id of the credential associated with the property. Applicable only for encrypted properties |
Response Codes
HTTP Code | Description |
---|---|
201 | Issue Tracking System instance was created successfully |
400 | Bad request |
401 | Authentication failure |
403 | Authorization failure (no access to resource) |
500 | Unexpected internal server error |
PUT
This PUT service will update all attributes of an issue tracking system with the given Id based on the attributes of the supplied JSON object.
API URL
http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance/{Id}
Request
Attributes | Type | Required | Description |
---|---|---|---|
instanceCode | String | Yes | The code of the Issue Tracking System. |
instanceName | String | Yes | The name of the Issue Tracking System. |
issueTrackingSystemId | Integer | Yes | The ID of the type of Issue Tracking System. |
description | String | No | The description of the Issue Tracking System. |
isActive | Boolean | Yes | Whether or not this Issue Tracking System is active. Defaults to true. |
properties | List<PropertyValue> | Depends | The properties associated with the type of Issue Tracking System: requirements depend on the Issue Tracking System selected. The JSON object must have all of the properties of the instance's ITS. Value for properties not included in input request will be cleared. More details about the PropertyValue object are included below. |
PropertyValue
Attributes | Type | Description |
---|---|---|
propertyName | String | This is the name of the property |
propertyValue | String | This is the value of the property |
credentialId | Long | Id of the credential associated with the property. Applicable only for encrypted properties |
Response
Attributes | Type | Required | Description |
---|---|---|---|
instanceId | Integer | No | Primary ID of the Issue Tracking System, created when first making an Issue Tracking System. |
instanceCode | String | Yes | The code of the Issue Tracking System |
instanceName | String | Yes | The name of the Issue Tracking System |
issueTrackingSystemId | Integer | Yes | The ID of the type of Issue Tracking System |
description | String | No | The description of the Issue Tracking System |
isActive | Boolean | No | Whether or not this Issue Tracking System is active. |
properties | List<PropertyValue> | No | The properties associated with the type of Issue Tracking System |
Each JSON ITS instance object contains a list of property value. The property value object has these attributes.
Attributes | Type | Description |
---|---|---|
propertyName | String | This is the name of the property |
propertyValue | String | This is the value of the property |
credentialId | Long | Id of the credential associated with the property. Applicable only for encrypted properties |
Response Codes
HTTP Code | Description |
---|---|
200 | Issue Tracking System instance was found and updated |
400 | Bad request |
401 | Authentication failure |
403 | Authorization failure (no access to resource) |
404 | Issue Tracking System instance not found |
500 | Unexpected internal server error |
PATCH
This PATCH service will update the information of the Issue Tracking System of the specified Id with the non-null parameters of the JSON. The parameters that are null will not be changed in the Issue Tracking System .
API URL
http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance/{Id}
The only required attribute is the Instance Id in the URL.
Request
Attributes | Type | Required | Description |
---|---|---|---|
instanceCode | String | No | The code of the Issue Tracking System. |
instanceName | String | No | The name of the Issue Tracking System. |
issueTrackingSystemId | Integer | No | The ID of the type of Issue Tracking System. |
description | String | No | The description of the Issue Tracking System. |
isActive | Boolean | No | Whether or not this Issue Tracking System is active. Defaults to true. |
properties | List<PropertyValue> | No | The properties associated with the type of Issue Tracking System: requirements depend on the Issue Tracking System selected. The JSON object doesn't need to have all of the properties of the ITS. Values provided in input list are the only ones updated. More details about the PropertyValue object are included below. |
PropertyValue
Attributes | Type | Description |
---|---|---|
propertyName | String | This is the name of the property |
propertyValue | String | This is the value of the property |
credentialId | Long | Id of the credential associated with the property. Applicable only for encrypted properties |
Response
Attributes | Type | Required | Description |
---|---|---|---|
instanceId | Integer | No | Primary ID of the Issue Tracking System, created when first making an Issue Tracking System. |
instanceCode | String | Yes | The code of the Issue Tracking System |
instanceName | String | Yes | The name of the Issue Tracking System |
issueTrackingSystemId | Integer | Yes | The ID of the type of Issue Tracking System |
description | String | No | The description of the Issue Tracking System |
isActive | Boolean | No | Whether or not this Issue Tracking System is active. |
properties | List<PropertyValue> | No | The properties associated with the type of Issue Tracking System |
Each JSON ITS instance object contains a list of property value. The property value object has these attributes.
Attributes | Type | Description |
---|---|---|
propertyName | String | This is the name of the property |
propertyValue | String | This is the value of the property |
credentialId | Long | Id of the credential associated with the property. Applicable only for encrypted properties |
Response Codes
HTTP Code | Description |
---|---|
200 | Issue Tracking System instance was found and updated |
400 | Bad request |
401 | Authentication failure |
403 | Authorization failure (no access to resource) |
404 | Issue Tracking System instance not found |
500 | Unexpected internal server error |
- style