Upgrade

Documentation about the upgrading/migrating process for Onify.
Please see a list of versions to upgrade too here https://support.onify.co/changelog.

Upgrade

If you are updating from same (minor) version, eg. from 1.x to 1.y or 2.x to 2.y you can do a on-box upgrade. Same goes for when you patch the system, eg. 1.x.a to 1.x.b.

Please also check our FAQ related to upgrade: https://support.onify.co/discuss?tag=upgrade.

Migration

If you are doing a major upgrade (eg. from 1.x to 2.x) you need to do a off-box and migrate data from the old instance to the new.

The migration process looks something like this.

  1. Preparations
  2. Setup new environment
  3. Migrate configuration, audit and items
  4. Migrate settings from configuration files
  5. Migrate custom item attribute mappings
  6. Migrate resources
  7. Migrate custom translations
  8. Modifiy custom scripts/integrations to Onify API

1. Preparations

Document current setup and secrets.

  1. Open the /config/config.json file in the API container (or Docker image) and document the following from the file: coreindex, mainindex, itemindex, eventindex and privateKey.
  2. Document admin username and password. If you do not have this, create a new admin user and and save that.
  3. Document current hostname.
  4. Document Elasticsearch username and password

2. Setup new environment

Setup new infrastructure via https://github.com/onify/install.

Make sure to set client_secret to same value as privateKey.

3. Migrate configuration, audit and items

To migrate configuration (users, roles, forms, workspaces, etc), audit and items from old instance to new, you need to use the /setup/database/migration endpoint on the new server.

Make sure that the new server is clean and new because things will be overwritten.

{
  "source": {
    "apiurl": "<api hostname>/api/v1",
    "connectionstring": "http://<elastic username>:<elastic password>@elastic:9200",
    "timezone": "Europe/Helsinki",
    "indexes": [
      "<coreindex>",
      "<mainindex>",
      "<itemindex>",
      "<eventindex>"
    ]
  }
}

Once the migrations is completed, you will need to login with "old" username and password.

4. Migrate settings from configuration files

In version 1.x of Onify, settings was stored in separated configuration files for APP and API. In version 2.x, every setting is now in the database (Elasticsearch). You need to manually migrate settings from the configuration files to the new settings structure. This section describes what settings should be copied from old to new and what the name of the setting are.

Migrate settings from API configuration file
  • logging.logLevel > logging_console_tags
  • logging.audit > audit_enabled
  • clientCode > [DEPRECATED]
  • db.* > [DEPRECATED]
  • defaultlanguage > default_language
  • privateKey > [DEPRECATED]
  • websockets.agent.url > [DEPRECATED]
  • websockets.agent.autoResponseTime > agentserver_autoresponsetime
  • websockets.agent.responseExpireTime > agentserver_responseexpiretime
  • mail.smtp.from > mail_from
  • mail.smtp.to > mail_to
  • mail.smtp.host > mail_smtp_host
  • mail.mailgun.from > mail_from
  • mail.mailgun.to > mail_to
  • mail.mailgun.domain > mail_mailgun_domain
  • mail.mailgun.api_key > mail_mailgun_apikey
  • api.* > [DEPRECATED]
  • webhookTimeout > webhook_timeout
  • variables.* > [DEPRECATED] (see Migrate custom variables section below)

If you have configured mail, you also need to set mail_method in settings to either mailgun or smtp.

Migrate custom variables

If you have set custom variables (variables.*) in the configuration file, you need to add these as custom settings. These custom settings will automatically get a _ prefix.

You can then address these custom settings using handlebars, like this:
{{settings._<custom_variable_name>}}

You need then to replace the old custom variables (eg. {{config.variables.customvar1}}) everywhere with the new custom setting (eg. {{settings._<customvar1>}}).

Migrate settings from APP configuration file
  • logging.logLevel > logging_console_tags
  • logging.log > [DEPRECATED]
  • logging.errorstack > [DEPRECATED]
  • clientCode > [DEPRECATED]
  • settings.defaultlanguage > default_language
  • settings.personalshortcuts > personal_shortcuts
  • settings.disabletooltips > [DEPRECATED]
  • settings.workspaceResultsPageSize > workspace_results_pagesize
  • settings.activitylog.enabled > [DEPRECATED] (use audit_page_query instead)
  • settings.activitylog.query > audit_page_query
  • settings.activitylog.excludedata > audit_page_exclude and audit_exclude_tags
  • favicon > custom_favicon
  • logo > custom_logo
  • customcss > custom_css
  • title > custom_title
  • contact.name > contact_name
  • contact.email > contact_email
  • contact.url > contact_url
  • contact.urltext > contact_urltext
  • contact.phone > contact_phone
  • analytics.google.trackingid > analytics_google_trackingid
  • analytics.google.userid > analytics_google_userid
  • api.internalUrl > [DEPRECATED]
  • api.externalUrl > [DEPRECATED]
  • api.admintoken > [DEPRECATED]
  • resources.github.user > resources_git_username
  • resources.github.password > resources_git_password
  • resources.github.token > `DEPRECATED]
  • resources.github.owner > resources_git_url
  • resources.github.repo > resources_git_url
  • storage.type > [DEPRECATED]
  • storage.bucket > [DEPRECATED]
  • storage.accesskey > [DEPRECATED]
  • storage.secret > [DEPRECATED]
  • storage.maxUploadsFilesSize > storage_maxattachmentsize
  • storage.maxAttachmentSize > storage_maxuploadsfilessize
  • intercom.app_id > intercom_appid
  • intercom.name > intercom_user_name
  • intercom.email > intercom_user_name
  • intercom.created_at > intercom_user_createddate
  • intercom.user_id > intercom_user_id
  • intercom._visibility > intercom_role
  • intercom.company.id > intercom_role
  • intercom.company.name > intercom_company_name
  • intercom.company.created_at > intercom_company_createddate

5. Migrate custom item attribute mappings

In version 1.x of Onify we managed custom item attribute mappings in Elastic via a json file (/setup/mapping/item/custom.json in the API container). This has now moved to settings in version 2.x. But we are also introducing one index per item type in 2.x as in 1.x we had one index for all item types. This means that we need to split up the mappings and assign to each item type.

Here is what you need to do to migrate:

  1. Open custom.json and copy all content
  2. Open a json editor or notepad and modify the structure an add item type, see example below
  3. Go to /admin/settings/item_attribute_index_mapping
  4. Paste modified json content into value field and click Save
  5. Reindex

Example migration

JSON structure in custom before modified

{
    "deliverydate": {
        "type": "date",
        "format": "YYYY-MM-dd"
    },
    "agreement_startdate": {
        "type": "date",
        "format": "YYYY-MM-dd"
    },
    "agreement_enddate": {
        "type": "date",
        "format": "YYYY-MM-dd"
    },
    "inventory_updated": {
        "type": "date",
        "format": "YYYY-MM-dd HH:mm:ss"
    },
    "inventory_lastlogin": {
        "type": "date",
        "format": "YYYY-MM-dd HH:mm:ss"
    },
    "published": {
        "type": "boolean"
    },
    "sla_time": {
        "type": "integer"
    },
    "_id": {
        "type": "integer"
    }            
}

JSON structure in custom after modified

{
    "asset": {
        "deliverydate": {
            "type": "date"
        },
        "inventory_updated": {
            "type": "date"
        },
        "inventory_lastlogin": {
            "type": "date"
        }
    },
    "contract": {
        "agreement_startdate": {
            "type": "date"
        },
        "agreement_enddate": {
            "type": "date"
        }
    },
    "software": {
        "published": {
            "type": "boolean"
        }
    }
    "ticket": {
        "sla_time": {
            "type": "integer"
        },
        "_id": {
            "type": "integer"
        }
    }
}

We recommend not setting format for date because all dates will be in UTC in version 2.x.

6. Migrate resources

In version 1.x of Onify, resources where stored in GitHub but in version 2.x GitHub is no longer required. But we also now support ALL general Git repos, not only GitHub.

In order to migrate resources you need to do the following:

  1. Copy or move files to local storage or other Git repo (optional)
  2. Move folder /templates/dashboard > /dashboards
  3. Move folder /templates/form > /forms
  4. Remove folder /config (after you migrated configuration to settings)
  5. Remove folder /locale
  6. Configure resources in settings (optional, see below)

Configuration of settings for Git resources

  1. Goto <new_hostname>/admin/settings?term=key:resources_git_url%20OR%20key:resources_git_password%20OR%20key:resources_git_branch%20OR%20key:resources_git_username
  2. Fill in Git url, credentials and branch

7. Migrate custom translations

In version 1.x translation where done by creating and editing custom.json files for each language. In version 2.x we are introducing strings, the new and better way to do translation. You have two options to migrate translations, either manually do it yourself or we at Onify can help you automate the process.

Manual migration

To migrate from custom.json files to strings, you need to perform the following steps:

Migrate entries from custom.json to Strings

  1. Open /locale/{locale}/custom.json via Admin/Resources in web app
  2. Go to Admin/Configuration/Strings
  3. Add new custom string
    3a. Set key as the unique name based on structure in json, eg. form.myform.mystring = form_myform_mystring.
    3b. Set string as the english text
    3c. Add a tag, eg. for forms, use something like form and myform
    3d, Add translation for every locale
  4. Done!

Replace translation variables in forms and dashboards pug files (if any)

  1. Use a good text/code editor that can do advanced search and replace
  2. Replace old translation variable with new strings variable, eg. replace t('form.myform.mystring') with t('_form_myform_mystring') (note: custom strings always have a "_" prefix).

Replace translation variables in item/table templates json files (if any)

  1. Use a good text/code editor that can do advanced search and replace
  2. Replace old translation variable with new strings variable, eg. replace <% item.myitemtype.myattribute %> with {{t '_item_myitemtype_myattribute'}}
Automatic migration

Please use our migrations script: https://github.com/onify/scripts/tree/main/translation_migration.

8. Modifiy custom scripts/integrations to Onify API

Because migration is done via a "off-box" migration the hostname usually change. But there are also some more changes in the API from version 1.x vs 2.x. Here is what you need to change in all your custom scripts that has a uri to the Onify Hub API.

  1. Change hostname to new hostname
  2. Change uri from ../api/v1.. to ../api/v2.
  3. Remove ../{locale}/.. (we moved translations)

We also made changes to some of the endpoints so please test all your scripts after upgrade.