• Upgrading to 3.0
  • Database
    • MySQL
  • Lifecycles
  • Search Result Formats
  • Changes to Ticket History
  • Retired Scrip Actions
  • Retired Scrip Conditions
  • RTIR Queue Summary Portlet
  • IP Custom Field
  • SLA Support
  • Notifications
• UPGRADING FROM 3.0.0 AND EARLIER
  • SubjectTag corrections
• UPGRADING FROM 3.0.1 AND EARLIER
  • add_constituency fixes
• UPGRADING FROM 3.0.2 AND EARLIER
  • SLA Custom Field

Upgrading to 3.0

The following describes some of the key components of the upgrade to RTIR 3.0 from previous versions of RTIR, specifically from RTIR 2.6. The other UPGRADING documents contain details for previous versions.

Database

The update steps implemented in the database upgrade script make significant changes to the database and its data. It's highly recommended that you save a DB backup before applying this script.

MySQL

If you are using MySQL you may want to apply the following indexes to improve the performance of the upgrade.

    CREATE INDEX UPGRADE_TRANSACTIONS_TYPE ON Transactions (Type, Field);
    CREATE INDEX UPGRADE_TRANSACTIONS_NEW ON Transactions(Field,ObjectType, Type, NewReference);
    CREATE INDEX UPGRADE_TRANSACTIONS_OLD on Transactions(Field,ObjectType, Type, OldReference);

These should be removed following a successful upgrade since they are unlikely to be useful in normal RTIR usage.

    DROP INDEX UPGRADE_TRANSACTIONS_TYPE ON Transactions;
    DROP INDEX UPGRADE_TRANSACTIONS_NEW ON Transactions;
    DROP INDEX UPGRADE_TRANSACTIONS_OLD ON Transactions;

Lifecycles

RT 4.0 introduces a new feature, lifecycles, which allowed us to replace RTIR's four State custom fields with four RTIR-specific lifecycles, delete the previous custom fields, and use RT's standard Status field.

This means that you have to review all customizations and replace any reference to State custom fields with Status. You should check templates, and scrips' conditions and actions.

For example the following code:

    $ticket->FirstCustomFieldValue('State');

should be replaced with:

    $ticket->Status;

Almost every format string in the $RTIRSearchResultFormats option had '__CustomField.{State}__' replaced with __Status__. Note this change as you port over your previous configuration files, and update your config if you have customizations.

Format strings of all saved searches are updated with with above change, but the regular expression doesn't attempt to be too clever and may skip some edge cases.

You can read more about lifecycles in RT's and RTIR's configuration files.

Search Result Formats

In addition to the changes for Status, new format strings are provided for $RTIRSearchResultFormats: ListIncidents and LookupTool.

Changes to Ticket History

To keep history intact, the upgrade script turns changes of the previous State custom fields into Status field changes. This a big change to the Tickets, Transactions and ObjectCustomFieldValues tables with updates and deletes mostly. Again, it's important to have a known good backup.

Retired Scrip Actions

Several scrip actions are no longer required because of the new lifecycles features, so these action modules and all scrips based on them are deleted from directories and the DB.

Started date is properly handled by lifecycles now, so the RTIR_SetStartedToNow scrip action is no longer needed.

IRs and Blocks still have some special status treatment, but it is handled by new scrips, so RTIR_SetIncidentReportState and RTIR_SetBlockState actions are not needed.

Investigations and Incidents don't need any special status treatment, so RTIR_SetInvestigationState and RTIR_SetIncidentState are deleted.

Retired Scrip Conditions

Just as some scrip actions have been removed, several scrip conditions also are no longer needed.

The RTIR_RequireStateChange condition gets deleted.

RTIR_BlockActivation gets deleted as well, however if you use it in custom scrips then you can replace it with a StatusChange condition that is part of RT. See the example in the upgrade script where RTIR's RTIR_ReopenTicket and RTIR_CloseTicket conditions get replaced with StatusChange.

RTIR Queue Summary Portlet

The /RTIR/Elements/QueueSummary portlet is deleted and replaced with RT's Quicksearch. Update your config in case you have a custom setting for RTIR_HomepageSettings. Users' preferences are updated automatically.

IP Custom Field

Code from RTIR to support the IP custom field has been merged into RT 4.0 and extended to support IPv6. The upgrade script changes the type of the IP field.

SLA Support

RTIR had a simple Service Level Agreements (SLA) implementation. RT::Extension::SLA was prototyped from it, but vastly improved. In RTIR 3.0 we delete this basic implementation in favor of the extension. The SLA custom field stays as the extension uses it as well. However, the dependency on the extension is not mandatory and there is no default config for it. Read the tutorial for administrators for more info "Service Level Agreements (SLA)" in AdministrationTutorial.

The following scrip actions and scrips that use them are deleted:

    RTIR_SetDueBySLA
    RTIR_SetDueCorrespond
    RTIR_SetDueReopen
    RTIR_SetDueToNow
    RTIR_UnsetDue
    RTIR_SetStartsByBizHours
    RTIR_SetStartsToNow

The following config options are no longer valid:

    $SLAModule
    $SLA
    $BusinessHours
    $SLA_Response_InHours
    $SLA_Response_OutOfHours
    $SLA_Reopen_InHours
    $SLA_Reopen_OutOfHours
    SLA key in %RTIR_CustomFieldsDefaults

The upgrade process itself won't modify any existing due dates, but if you are using the older SLA configuration, you need to install RT::Extension::SLA and port over your current SLA configuration to the new module. If you are installing the module for the first time, you will need to run the 'make initdb' step to get the proper scrips installed. You should then test with the new SLA configurations in a dev environment to verify that due dates are being properly set for all relevant actions (create, respond, resolve, etc.).

If you wish to convert to the RT::Extension::SLA module, you will need to take care with the SLA Custom Fields. RT::Extension::SLA will install a new Global Custom Field named SLA. This is in addition to the SLA field that RTIR previously provided on the Incident Reports Queues. You should navigate to Tools -> Configuration -> Custom Fields and select the SLA Custom Field which is marked as being "Global" in the "Applied" column. Uncheck the "Enabled" box to disable the global SLA field.

If you plan to enforce SLAs on your Investigations or Blocks Queues, you should select the SLA Custom Field marked as "Incident Reports" in the Applied" column, click on the "Applies To" link in the upper right menu and apply it to the other Queues where you wish to enforce an SLA. Do not enable SLA on Incidents without disabling the RTIR scrips that manage the Due date on the Incidents Queues.

You will need to review RT::Extension::SLA documentation and construct a configuration that matches up with how you need to set up SLAs. You can find more about RTIR's Due date management and SLAs in docs/AdministrationTutorial.

Notifications

New installs of RTIR notify Ccs when launching an Investigation.

If you would like your updgraded RTIR to notify Ccs when launching Investigations, you can make a Global or Investigations-specific Scrip from Tools -> Configuration -> Global -> Scrips or Tools -> Configuration -> Queues -> Investigations -> Scrips with:

    Description: On Create Notify Ccs
    Condition:   On Create
    Action:      Notify Ccs
    Template:    Global Template: Correspondence

UPGRADING FROM 3.0.0 AND EARLIER

SubjectTag corrections

During the upgrade from 2.4 to 2.6, instructions were provided to begin including Queue SubjectTags in outgoing mail. New installs of 2.6.0 also used SubjectTags in templates. However, they suggested an old-style

    [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]

Instead, you should use the more modern

    [{$Ticket->SubjectTag} #{$Ticket->id}]

Because correspondence templates are frequently modified, it is not practical to script updates and they will need to be done through the UI.

UPGRADING FROM 3.0.1 AND EARLIER

add_constituency fixes

If you previously used the etc/add_constituency script to set up a Constituency, it did not set your Custom Field rights properly. The version included in 3.0.2 can safely be re-run as

    etc/add_constituency --name Name

It will apply the missing rights on custom fields.

As part of this fix, there has been a behavior change. Constituency Duty Teams are now given rights on all Custom Fields applied to RTIR queues (modify or read only depending on the type of duty team). Previously they were only granted rights on the default RTIR Custom Fields.

Rights are managed at the Custom Field level by this script, so it's straightforward to remove rights after constituency creation.

UPGRADING FROM 3.0.2 AND EARLIER

SLA Custom Field

See new additional notes in the "SLA Support" section if you are upgrading within the 3.0 series.

← Back to index