Preparing for Insight 8.4

The following page describes the breaking changes that are introduced in Insight 8.4. In order to upgrade to 8.4 or higher version of Insight this document should be read in order to prepare to upgrade the Insight version. 

For frequently asked questions about the upgrade to Insight 8.4, please see the Insight 8.4 FAQs page.

Database changes

Depending on the database type you might need to make manual changes. To make Insight more robust we have changed some database tables but we have seen issues in the Atlassian Active Object Framework during the upgrade process. This means that if you are using the below mentioned affected database types you need to follow the instructions to upgrade Insight. 

Depending on the database type you are using you might have to follow below steps when upgrading to Insight 8.4 or higher version. You need to do this in the correct order.

SQL Server

1. Before installation, query the database: 

   ALTER TABLE AO_8542F1_IFJ_OBJ_ATTR_VAL DROP CONSTRAINT fk_ao_8542f1_ifj_obj_attr_val_object_attribute_id;

2. Install new Insight version.

3. After installation, query the database. 

   ALTER TABLE AO_8542F1_IFJ_OBJ_ATTR_VAL ADD CONSTRAINT fk_ao_8542f1_ifj_obj_attr_val_object_attribute_id
   FOREIGN KEY (OBJECT_ATTRIBUTE_ID) REFERENCES AO_8542F1_IFJ_OBJ_ATTR(ID);

MySQL

1. Before installation, query the database: 

   ALTER TABLE AO_8542F1_IFJ_OBJ_ATTR_VAL DROP FOREIGN KEY fk_ao_8542f1_ifj_obj_attr_val_object_attribute_id;

2. Install new Insight version.

3. After installation, query the database:

   ALTER TABLE AO_8542F1_IFJ_OBJ_ATTR_VAL ADD CONSTRAINT fk_ao_8542f1_ifj_obj_attr_val_object_attribute_id
   FOREIGN KEY (OBJECT_ATTRIBUTE_ID) REFERENCES AO_8542F1_IFJ_OBJ_ATTR(ID);

H2

1. Before installation, query the database: 

   ALTER TABLE AO_8542F1_IFJ_OBJ_ATTR_VAL ADD CONSTRAINT fk_ao_8542f1_ifj_obj_attr_val_object_attribute_id
   FOREIGN KEY (OBJECT_ATTRIBUTE_ID) REFERENCES AO_8542F1_IFJ_OBJ_ATTR(ID);

2. Install new Insight version.

3. After installation, query the database:

   ALTER TABLE PUBLIC.AO_8542F1_IFJ_OBJ_ATTR_VAL ADD CONSTRAINT fk_ao_8542f1_ifj_obj_attr_val_object_attribute_id FOREIGN KEY  (OBJECT_ATTRIBUTE_ID) REFERENCES PUBLIC.AO_8542F1_IFJ_OBJ_ATTR(ID);

PostgreSQL & Oracle

No extra actions required for these databases.

New database map

The 8.4 release will affect the structure of our database. A digram of the the new database is shown below:

Event changes (Automation)

REMOVEDObject Cloned - The object clone event has been removed.

Old reports and gadgets

REMOVED All old reports and gadgets are removed. So before installation of Insight 8.4, you should make sure to migrate all deprecated gadgets to the new one called "Insight Widget". To do that you need to create a "Report", see Reports, of the type you want to display and then create a Jira gadget from the report and replace it with the old one. 

REST API

The following changes describes the changes done in the REST API. It is of importance if you are using a custom integration that consumes the Insight REST API. These are breaking changes for the Insight v1 API. 

Objects CHANGED

Queries related to objects

Attachment CHANGED

General - Date and time request and response types

In previous versions Insight REST API always returned all date and time information adjusted to the logged in users timezone as well as the configured date (or date time) format configured on the Jira server. To make the API more integration friendly all dates and times are changed to ISO8601 format. 

When mutating attribute values in Insight the input is expected to be sent in ISO8601 format as well. This change is made backward compatible meaning that the input will be assumed to be in ISO8601 format if the input fails to be parsed in this way the input will be parsed using the old way i.e. based on the Jira settings and the user timezone. 

Date attribute type

All attribute values of type Date will be returned as an ISO8601 formatted date e.g. 2017-10-26. The expected input when creating or updating is the same format. 

Comparison between old and new

Old response

"objectAttributeValues": [
  {
    "displayValue": "29/Nov/2019",
    "value": "29/Nov/2019"
   }
]

New response

"objectAttributeValues": [
  {
    "value": "2019-11-29",
    "searchValue": "2019-11-29",
    "displayValue": "29/Nov/2019",
    "referencedType": false
  }
]

DateTime attributes

All date time attributes are now returned in ISO8601 format in UTC with milliseconds e.g. 2010-11-26T07:21:37.123Z. Input is expected in ISO8601 format in an arbitrary timezone that is added as described by the standard e.g. 2010-11-26T06:21:37+0100. 

Comparison between old and new (note timezone difference in the new response)

Old response

"objectAttributeValues": [
  {
    "displayValue": "26/Nov/19 9:07 AM",
    "value": "26/Nov/19 9:07 AM"
  }
]

New response

"objectAttributeValues": [
  {
    "value": "2019-11-26T08:07:08.063Z",
    "searchValue": "2019-11-26T08:07:08.063Z",
    "displayValue": "26/Nov/19 9:07 AM",
    "referencedType": false
  }
]

Timestamps

All timestamps in Insight are now represented in the REST API in ISO8601 format in UTC. That is all created, updated, started, finished etc. are returned in ISO8601 format in UTC with milliseconds e.g. 2010-11-26T07:21:37.123Z

Comparison between old and new

Old response

"objectType": {
  "abstractObjectType": false,
  "created": "24/Oct/2019 01:11 AM",
  "icon": {
    "id": 29,
    "name": "Computer",
    "url16": "https://url/rest/insight/1.0/objecttype/143477/icon.png?size=16&inherited=true&abstract=false&time=1571919096176",
    "url48": "https://url/rest/insight/1.0/objecttype/143477/icon.png?size=48&inherited=true&abstract=false&time=1571919096176"
  },
  "id": 143477,
  "inherited": true,
  "name": "Laptop",
  "objectCount": 0,
  "objectSchemaId": 58583,
  "parentObjectTypeId": 143476,
  "parentObjectTypeInherited": true,
  "position": 0,
  "type": 0,
  "updated": "24/Oct/2019 01:11 AM"
}

New response

"objectType": {
  "id": 143477,
  "name": "Laptop",
  "type": 0,
  "icon": {
    "id": 29,
    "name": "Computer",
    "url16": "https://url/rest/insight/1.0/objecttype/143477/icon.png?size=16",
    "url48": "https://url/rest/insight/1.0/objecttype/143477/icon.png?size=48"
  },
  "position": 0,
  "created": "2019-10-24T00:11:02.891Z",
  "updated": "2019-10-24T00:11:02.891Z",
  "objectCount": 0,
  "objectSchemaId": 58583,
  "inherited": true,
  "abstractObjectType": false,
  "parentObjectTypeInherited": true
}

Post functions

Assign Object based on Jira custom field - removed

The post function Assign Object based on Jira custom field is now removed (it was deprecated in Insight 5.3). Please use the "Assign Objects from an IQL query based on data from an issue" post function instead.

JQL Functions

attributeValue(attribute, operator, value) - removed

The JQL function attributeValue("","","") has been removed and is replaced with the IQLFunction in JQL. The replacement will look similar to this

JAVA API

The JAVA API is used for the groovy scripting and custom integrations with Insight. 

Facade

ObjectFacade

ObjectSchemaFacade

ObjectTypeAttributeFacade

ObjectTypeFacade

ObjectTicketFacade (New facade)

Model classes

The model classes are used in some of the ObjectFacade methods as parameters and response objects. 

ObjectAttributeValueBean

• Added getId() to retrieve the id
• Changed toString() from "[" + getValue() + "]" to "[" + id + "(" + getValue() + ")]"

RoleBean

• getType() no longer return int but return a RoleType
• setType(int type) is changed to setType(RoleType)

ObjectBean

• getObjectAttributeBeans() only returns ObjectAttributeBean's which has a value. 

Event Classes

InsightObjectAsyncEvent

• getRunAsUser() returns an InsightUser instead of ApplicationUser. There are several ways to get an ApplicationUser:

*) Use service "com.atlassian.jira.user.util.UserManager" and the method "getUserByKey(String userKey)"

*) Use static "com.atlassian.jira.user.ApplicationUsers.byKey(String userKey)" 

Import 

CSV import

The CSV import will now validate the content stream that the content is indeed a CSV file. This might affect import configurations that are importing CSV from a URL.