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.

Preparations
Setup new environment
Migrate configuration, audit and items
Migrate settings from configuration files
Migrate custom item attribute mappings
Migrate resources
Migrate custom translations
Modifiy custom scripts/integrations to Onify API

1. Preparations

Document current setup and secrets.

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.
Document admin username and password. If you do not have this, create a new admin user and and save that.
Document current hostname.
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:

Open custom.json and copy all content
Open a json editor or notepad and modify the structure an add item type, see example below
Go to /admin/settings/item_attribute_index_mapping
Paste modified json content into value field and click Save
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:

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

Configuration of settings for Git resources

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
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

Open /locale/{locale}/custom.json via Admin/Resources in web app
Go to Admin/Configuration/Strings
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
Done!

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

Use a good text/code editor that can do advanced search and replace
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)

Use a good text/code editor that can do advanced search and replace
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.

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

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