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.
- 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
andprivateKey
. - 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 asprivateKey
.
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 eithermailgun
orsmtp
.
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]
(useaudit_page_query
instead)settings.activitylog.query
>audit_page_query
settings.activitylog.excludedata
>audit_page_exclude
andaudit_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 likeform
andmyform
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')
witht('_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.
Updated about 2 years ago