Ticket-based IT Experience 1.5.0 Update Guide

Deep-dive guide for Service Administrators on how to update to version 1.5.0 of the Ticket-based IT Experience application.

1. Check Release notes
2. Update your application version
3. Review the application update log
   1. Apply deletions to the application
   2. Changes to application System Properties

   3. Changes in the menu structure of the application

   4. New fields added to HappySignals Feedbacks table

   5. Meet HappyConstants

      1. "HappySignals Feedback inserted" - business rule

      2. "HappySignals Feedback Import" - transform map

4. Post update checks
5. HappySignals Support

Check Release Notes

First, check out the Release Notes for an overview of what's new in this version.

Update your application version

Always update your sub-production instances first and only then proceed to update your production instance.

In your ServiceNow instance navigate to System Applications > All Available Applications > Installed.

Find the application you want to update and click the "Update" button.

Let the update run through, this usually takes a minute or two. 

Review the application update log

Once the update has been completed, click on the "View update log" button to see what records have been updated and what have been left untouched by the update process.

ServiceNow protects any customisations you might have done in the application and will not apply updates to any records that have been altered by the client.

Additionally, ServiceNow does not automatically apply record deletions published by the developer and these need to be applied manually after the update.

Apply deletions

In this application version, we've made some changes to System Property Categories to make the application configurations easier. To make the changes take effect, some record deletions must be applied within the application in your ServiceNow instance.

Deletions appear as skipped records on the application update log where they can be applied manually by admins. Note that the skipped record list does not only compose of record deletions.

To apply a deletion:

1. Search the skipped record list with a deletion name listed in the table below.
2. Open the record and review differences, using the "Resolve Conflicts" option.
3. In the review window, select "Revert to Base System" to apply the update/deletion as published by the developer.

Below you can find a list of deletions that should be applied manually as part of this update.

sys_properties_category_m2m_32a7118edbaf3410335816494896195c
sys_properties_category_m2m_3b7c4ecfdbe1d3409b18735a8c961919
sys_properties_category_m2m_3c01bc32db9a6f40dfd83c9b7c9619e3
sys_properties_category_m2m_523d569c1bd2a0109dbd64e8bc4bcb96
sys_properties_category_m2m_58ade18a1bb6e410d688c80f034bcb48
sys_properties_category_m2m_61fed997db353410335816494896198c
sys_properties_category_m2m_72544f39db197740dfd83c9b7c9619c0
sys_properties_category_m2m_75bd5206db122f40dfd83c9b7c9619f3
sys_properties_category_m2m_b77c4ecfdbe1d3409b18735a8c96191b
sys_properties_category_m2m_caee5d57db353410335816494896191a
sys_properties_category_m2m_e0f39d1adb7c9700dfd83c9b7c961948
sys_properties_category_m2m_e49d618a1bb6e410d688c80f034bcbea
sys_properties_category_m2m_edbd5206db122f40dfd83c9b7c9619f0
sys_user_role_contains_32a3602edb8d93009b18735a8c9619bd
sys_export_definition_55d99d7b1b77e410d688c80f034bcb34

We've made some changes to System Properties to make the application configurations easier. Below is a summary of changes that might affect your data configurations.

Changes in the menu structure of the application

We've cleaned up the application menu structure and updated some of the menu names to be more descriptive.

New fields added to HappySignals Feedbacks table

With this update, we are bringing a couple of new fields to the HappySignals Feedbacks table and also rethought the list and form structure for the feedback views.

Meet HappyConstants

Version 1.5.0 brings a new script include to the application which is your place for defining rules earlier defined in various other scripts within the application.

You don't need to pay attention to this if you have not done any customizations to the application scripts, but if you have modified any of the following parts in the application this has an impact on your update:

"HappySignals Feedback inserted" - business rule

This business rule does two things, updates the related ticket's state and adds a work note to the ticket when HappySignals response is written to ServiceNow.

Before rules related to the state update were defined in the business rule, but now the rule sets for state updates have been moved to HappyConstants.

If you have modified the business rule, make sure to replicate your table-based state update logic to HappyConstants and then revert the business rule to its default state.

Default definitions in HappyConstants are described below:

/* TICKET UPDATE RULES */

HappyConstants.ENABLE_WORKNOTE = gs.getProperty('x_pgo_happysignals.enableWorknoteInsertion', 'false') == 'true' ? true : false;

/** HappyConstants.TICKET_STATE_RULES
 *  Used in "HappySignals Feedback inserted" - business rule
 *  Defines table based rules to updating record states when feedback record is created to ServiceNow.
 * */
HappyConstants.TICKET_STATE_RULES = {
    "incident": {
        "state_field": "incident_state",
        "allowed_states": gs.getProperty('x_pgo_happysignals.incident_statuses', "").split(','),
        "set_new_state": gs.getProperty('x_pgo_happysignals.closeIncident', 'false'),
        "new_state": "7"
    },
    "sc_req_item": {
        "state_field": "",
        "allowed_states": [],
        "set_new_state": false,
        "new_state": ""
    },
    "sc_request": {
        "state_field": "",
        "allowed_states": [],
        "set_new_state": false,
        "new_state": ""
    },
    'interaction': {
        "state_field": "",
        "allowed_states": [],
        "set_new_state": false,
        "new_state": ""
    }
};

/* TICKET UPDATE RULES END */

How do the state update rules work?

Rule sets are defined as table-specific objects. To define a new rule set, add a new object to the list with a table name as the object key. Then add your rules definitions within the object:

• "state_field" - what is the state field name on this table
• "allowed_states" - what are the state values that allow an update to be applied. If the related ticket's state is something else than the listed values then the update is not applied.
• "set_new_state" - should a new state be applied for records from this table.
• "new_state" - the state value that is applied if the update conditions are met. The value must match the type of value accepted by the defined "state_field".
  

Below is an example definition for updating a Change Request state from "Open" or "In Progress" to "Closed Complete" when a HappySignals response record is added to ServiceNow.

'change_request': {
    "state_field": "state",
    "allowed_states": [1,2], // 1 = "Open", 2 = "In progress"
    "set_new_state": true,
    "new_state": 3 // 3 = "Closed"
}

"HappySignals Feedback Import" - transform map

The integration from HappySignals back to ServiceNow uses a transform map to enrich the response information with the latest details from the related ticket. This information contains details such as the agent resolving or closing the ticket, the associated assignment group etc. 

The transform map consists of one "onBefore" transform script and multiple "Field Map" definitions.

If you have modified or made a copy of the default transform map functionalities make sure to move your changes to the new HappyConstants model when applicable.

onBefore Transform Script constants

There are two constants that affect the transform script functionality:

INTEGRATION_TABLES

Defines the list of table names which are used to look up whether a particular ticket can be found in the ServiceNow instance. The integration uses "ticketId", usually the ticket number, returned from the API to make the lookup. The first table where a match is found is used as the basis for later processing. 

LOG_RESPONSE_IMPORTS 

Defines if all successful record imports are logged to ServiceNow "System Logs". You should only enable this when troubleshooting issues with the integration.

/** HappyConstants.INTEGRATION_TABLES
 *  Used in  "HappySignals Feedback Import" -transform map onBefore script
 *  List of table names that are used to look for records related to feedbacks.
 * */
HappyConstants.INTEGRATION_TABLES = ['incident', 'sc_req_item', 'sc_request', 'interaction', 'change_request'];


/** HappyConstants.LOG_RESPONSE_IMPORTS
 *  Used in  "HappySignals Feedback Import" -transform map onBefore script
*  If true logs every succesfull response report import
* */
HappyConstants.LOG_RESPONSE_IMPORTS = false;

Field Map constants

There are six constants that affect field map functionalities listed below. Each rule set is defined as table-specific and rules are applied based on the look-up result from the constant INTEGRATION_TABLES. 

There are two types of rule sets, reference field population and GlideList population.

• Reference fields pick the first field value that is found while going through an array of field names.
• GlideList population collects field values from multiple different fields and can also look up fields from other associated records.

RELATED_USER_RULES

These rules define who is determined as the Survey Responder. Your resolution/closure email containing HappySignals rating scale should only be delivered to one person associated with the ticket and this rule should follow that definition. 

/** HappyConstants.RELATED_USER_RULES
 *  Used in "HappySignals Feedback Import" - transform map
 *  Defines table based rules for populating related_user (Survey Responder) field in HappySignals Feedbacks table.
 *  Gets single value from first match on field array.
 * */
HappyConstants.RELATED_USER_RULES = {
    'incident': ['caller_id'],
    'sc_req_item': ['request.requested_for'],
    'sc_request': ['requested_for'],
    'interaction': ['opened_for']
};

RESOLVED_BY_USER_RULES

These rules define who is determined as the person resolving or closing the ticket. See an example below for "sc_req_item" picking up a fallback value if the first defined field doesn't hold a value.

/** HappyConstants.RESOLVED_BY_USER_RULES
 *  Used in "HappySignals Feedback Import" - transform map
 *  Defines table based rules for populating resolved_by_user (Resolved by User) field in HappySignals Feedbacks table.
 *     Gets single value from first match on field array.
 * */
HappyConstants.RESOLVED_BY_USER_RULES = {
    'incident': ['resolved_by'],
    'sc_req_item': ['assigned_to', 'request.assigned_to'],
    'sc_request': ['assigned_to'],
    'interaction': ['assigned_to']
};

CLOSING_ASSIGNMENT_GROUP_RULES

These rules define who is determined as the assignment group resolving or closing the ticket. See an example below for "sc_req_item" picking up a fallback value if the first defined doesn't hold a value.

/** HappyConstants.CLOSING_ASSIGNMENT_GROUP_RULES
 *  Used in "HappySignals Feedback Import" - transform map
 *  Defines table based rules for populating closing_assignment_group (Closing Assignment Group) field in HappySignals Feedbacks table.
 *     Gets single value from first match on field array.
 * */
HappyConstants.CLOSING_ASSIGNMENT_GROUP_RULES = {
    'incident': ['assignment_group'],
    'sc_req_item': ['assignment_group', 'request.assignment_group'],
    'sc_request': ['assignment_group'],
    'interaction': ['assignment_group']
};

RELATED_USERS_RULES

These rules define who are determined as the agents related to the ticket. Users listed here will have access to the response record in ServiceNow.  Multiple users can be collected directly from the ticket and also associated records in other tables.

For example, related agents for Requests are collected from all requested items where the "Request" is referenced and from all tasks where the requested items are referenced as the task parent.

'sc_request': {
        'fields': [],
        'linkedRecords': {
            'sc_req_item': {
                'fields': ['assigned_to', 'closed_by'],
                'referenceField': 'request',
                'linkedRecords': {
                    'task': {
                        'fields': ['assigned_to', 'closed_by'],
                        'referenceField': 'parent'
                    }
                }
            }
        }
    }

Default definitions:

/** HappyConstants.RELATED_USERS_RULES
 *  Used in "HappySignals Feedback Import" - transform map
 *  Defines table based rules for populating related_users (Related Agents) field in HappySignals Feedbacks table.
*   Gets multiple values from all matching fields on main record and linked records. Supports recursive structure on linkedRecords.
 * */
HappyConstants.RELATED_USERS_RULES = {
    'incident': {
        'fields': ['assigned_to', 'closed_by', 'resolved_by'],
        'linkedRecords': {
            'task': {
                'fields': ['assigned_to', 'closed_by'],
                'referenceField': 'parent'
            }
        }
    },
    'sc_req_item': {
        'fields': ['assigned_to', 'closed_by'],
        'linkedRecords': {
            'task': {
                'fields': ['assigned_to', 'closed_by'],
                'referenceField': 'parent'
            }
        }
    },
    'sc_request': {
        'fields': [],
        'linkedRecords': {
            'sc_req_item': {
                'fields': ['assigned_to', 'closed_by'],
                'referenceField': 'request',
                'linkedRecords': {
                    'task': {
                        'fields': ['assigned_to', 'closed_by'],
                        'referenceField': 'parent'
                    }
                }
            }
        }
    },
    'interaction': {
        'fields': ['assigned_to']
    }
};

RELATED_ASSIGNMENT_GROUPS_RULES

These rules define what are determined as the assignment groups related to the ticket. Multiple groups can be collected directly from the ticket and also associated records in other tables.

For example, related assignment groups for Requests are collected from all requested items where the parent "Request" is referenced and from all tasks where any of the requested items are referenced as the task parent.

/** HappyConstants.RELATED_ASSIGNMENT_GROUPS_RULES
 *  Used in "HappySignals Feedback Import" - transform map
 *  Defines table based rules for populating related_assignment_groups (Related Assignment Groups) field in HappySignals Feedbacks table.
 *     Gets multiple values from all matching fields on main record and linked records. Supports recursive structure on linkedRecords.
 * */
HappyConstants.RELATED_ASSIGNMENT_GROUPS_RULES = {
    'incident': {
        'fields': ['assignment_group'],
        'linkedRecords': {
            'task': {
                'fields': ['assignment_group'],
                'referenceField': 'parent'
            }
        }
    },
    'sc_req_item': {
        'fields': ['assignment_group'],
        'linkedRecords': {
            'task': {
                'fields': ['assignment_group'],
                'referenceField': 'parent'
            }
        }
    },
    'sc_request': {
        'fields': ['assignment_group'],
        'linkedRecords': {
            'sc_req_item': {
                'fields': ['assignment_group'],
                'referenceField': 'request',
                'linkedRecords': {
                    'task': {
                        'fields': ['assignment_group'],
                        'referenceField': 'parent'
                    }
                }
            }
        }
    },
    'interaction': {
        'fields':['assignment_group']
    }
};

Post update checks

After any application make sure to run functional testing in a non-production environment before installing any updates to production.

Additionally, after each update, check that all scheduled jobs within the application are set to"Active" as these can get deactivated as part of the update process.

HappySignals Support

If you encounter issues, have questions or need support with the update contact our support at

support@happysignals.com