Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

...

Property NameTypeRequiredDescriptionExample Property Value
JIRA_USER_NAMEStringYesUser name to login into the JIRA serverusername
JIRA_PASSWORDStringYesAPI token or password to login into the JIRA server. Jira Documentation contains more information on generating API tokens.password
JIRA_PORTIntegerYesPort to access the JIRA system1234
JIRA_TICKET_REST_PATTERNStringYesPattern to update/retrieve information on a given JIRA ticket on the JIRA server/rest/api/2/issue/{JIRA_ISSUE}
JIRA_TICKET_URL_PATTERNStringYesPattern to link to a given JIRA ticket on the JIRA server/browse/{JIRA_ISSUE}
JIRA_URLStringYesURL to the JIRA systemhttp://myjira.atlassian.net

...

Request

Parameter
Required
Type
Description
IdYesURLURL parameter for the Id which is used to find and return an issue tracking system

Include Page
REST V1 ITS Instance Response
REST V1 ITS Instance Response

Response Codes

HTTP CodeDescription
200Issue Tracking System instance was found and returned
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Issue Tracking System instance not found
500Unexpected internal server error


Expand
titleGET by ID Example

Example

If we had an Issue Tracking System in our database with an Id of 11101 with the following attributes

Code Block
themeEclipse
titleIssue Tracking System - 11101
{
	"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
		}
	]
}


When we run a GET request at the following URL

http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance/11101

The GET request would return the following JSON Issue Tracking System object

Code Block
themeEclipse
titleIssue Tracking System - 11101
{
	"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
		}
	]
}


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.

Info
titleAPI 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}

...

Attributes
Type
Required
Description
instanceCodeStringYesThe code of the Issue Tracking System.
instanceNameStringYesThe name of the Issue Tracking System.
issueTrackingSystemIdIntegerYesThe ID of the type of Issue Tracking System.
descriptionStringNoThe description of the Issue Tracking System.
isActiveBooleanYesWhether or not this Issue Tracking System is active. Defaults to true.
propertiesList<PropertyValue>DependsThe 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

AttributesTypeDescription
propertyNameStringThis is the name of the property
propertyValueStringThis is the value of the property
credentialIdLongId of the credential associated with the property. Applicable only for encrypted properties

Include Page
REST V1 ITS Instance Response
REST V1 ITS Instance Response

Response Codes

...

Attributes
Type
Required
Description
instanceCodeStringYesThe code of the Issue Tracking System.
instanceNameStringYesThe name of the Issue Tracking System.
issueTrackingSystemIdIntegerYesThe ID of the type of Issue Tracking System.
descriptionStringNoThe description of the Issue Tracking System.
isActiveBooleanYesWhether or not this Issue Tracking System is active. Defaults to true.
propertiesList<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.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

AttributesTypeDescription
propertyNameStringThis is the name of the property
propertyValueStringThis is the value of the property
credentialIdLongId of the credential associated with the property. Applicable only for encrypted properties

Include Page
REST V1 ITS Instance Response
REST V1 ITS Instance Response

Response Codes

HTTP CodeDescription
200Issue Tracking System instance was found and updated
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Issue Tracking System instance not found
500Unexpected internal server error


Expand
titlePUT Example

Example

If we had an issue tracking system in our database with an Id of 11223 and had the following attributes

Code Block
themeEclipse
titleIssue Tracking System - 11223
{
	"instanceId": 11223,
	"instanceCode": "ITS",
	"instanceName": "ITS Name",
	"issueTrackingSystemId": 1,
	"description": "ITS example",
	"isActive": false,
	"properties":
	[
		{
			"propertyName": "JIRA_PASSWORD",
			"propertyValue": "*****",
			"credentialId": 10282
		},
		{
			"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
		}
	]
}

When we run a PUT request at the following URL

http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance/11223

And the PUT request receives the following JSON issue tracking system object,

Code Block
themeEclipse
titleIssue Tracking System - 11223
{
	"instanceId": 1,
	"instanceCode": "NEWITS",
	"instanceName": "New Name",
	"issueTrackingSystemId": 1,
	"description": "PUT example",
	"isActive": true,
	"properties":
	[
		{
			"propertyName": "JIRA_PASSWORD",
			"propertyValue": "updatedpassword",
			"credentialId": null
		},
		{
			"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
		}
	]
}

The PUT request would then update the Issue Tracking System with Id 11223 and return the following JSON Issue Tracking System object.

Code Block
themeEclipse
titleIssue Tracking System - 11223
{
	"instanceId": 11223,
	"instanceCode": "NEWITS",
	"instanceName": "New Name",
	"issueTrackingSystemId": 1,
	"description": "PUT example",
	"isActive": true,
	"properties":
	[
		{
			"propertyName": "JIRA_PASSWORD",
			"propertyValue": "*****",
			"credentialId": 10282
		},
		{
			"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
		}
	]
}


PATCH

...

Attributes
Type
Required
Description
instanceCodeStringNoThe code of the Issue Tracking System.
instanceNameStringNoThe name of the Issue Tracking System.
issueTrackingSystemIdIntegerNoThe ID of the type of Issue Tracking System.
descriptionStringNoThe description of the Issue Tracking System.
isActiveBooleanNoWhether or not this Issue Tracking System is active. Defaults to true.
propertiesList<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

AttributesTypeDescription
propertyNameStringThis is the name of the property
propertyValueStringThis is the value of the property
credentialIdLongId of the credential associated with the property. Applicable only for encrypted properties

Include Page
REST V1 ITS Instance Response
REST V1 ITS Instance Response

Response Codes

HTTP CodeDescription
200Issue Tracking System instance was found and updated
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Issue Tracking System instance not found
500Unexpected internal server error


Expand
titlePATCH Example

Example

If we had an issue tracking system in our database with an Id of 11223 and had the following attributes

Code Block
themeEclipse
titleIssue Tracking System - 11223
{
	"instanceId": 11223,
	"instanceCode": "NEWITS",
	"instanceName": "New Name",
	"issueTrackingSystemId": 1,
	"description": "PUT example",
	"isActive": true,
	"properties":
	[
		{
			"propertyName": "JIRA_PASSWORD",
			"propertyValue": "*****",
			"credentialId": 10282
		},
		{
			"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
		}
	]
}

When we run a PATCH request at the following URL

http://host:port/flexdeploy/rest/v1/topology/integrations/itsinstance/11223

And the PATCH request receives the following JSON issue tracking system object,

Code Block
themeEclipse
titleIssue Tracking System - 11223
{
	"instanceId": null,
	"instanceCode": null,
	"instanceName": "Updated Password",
	"issueTrackingSystemId": null,
	"description": null,
	"isActive": null,
	"properties":
	[
		{
			"propertyName": "JIRA_PASSWORD",
			"propertyValue": "newJiraPassword",
			"credentialId": null
		}
	]
}

The PATCH request would then update the issue tracking system with Id 11223 and return the  following JSON issue tracking system object.

Code Block
themeEclipse
titleIssue Tracking System - 11223
{
	"instanceId": 11223,
	"instanceCode": "NEWITS",
	"instanceName": "Updated Password",
	"issueTrackingSystemId": 1,
	"description": "PUT example",
	"isActive": true,
	"properties":
	[
		{
			"propertyName": "JIRA_PASSWORD",
			"propertyValue": "*****",
			"credentialId": 10282
		},
		{
			"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
		}
	]
}