Custom Protocol

George Thomas itris Expert

Introduction

The introduction of the itris custom protocol allows itris users to share records between one another by simply sharing a link.

As detailed here, itris users can select ‘Copy Link’ when sharing a record which will generate and itris specific URL that they can share to other itris users. When opened, this link will load in the browser, before communicating directly with the itris app and opening the record.

These URLs can also be generated manually and embedded into third party apps, skipping the need to load in the browser first.

Creating itris URLs

The itris protocol will be registered on itris users machines automatically when they download the latest itris launcher. Once this is done, itris will know to respond to any links starting with itris:.

To create an itris URL, there are a few parameters which a third party must know from the itris database. These are as follows:

  • Database URL (dburl) - Following an update to itris, the connection details the itris launcher requires have been updated, solely relying on a Database URL along with a username and password to connect. Each itris database has a different Database URL, but this can be obtained from the relevant client. In all cases the format of this will be: https://<hostname>:<port>
  • Record Type (rt) - At launch, Custom Protocols can support one of the 5 main record types. The values are:
    • Applicant
    • Company
    • Contact
    • Job
    • Placement
  • Record Id (id) - This will be the itris Id number of the record you wish to open. Record Ids are available to retrieve through the API.
  • Action (act) - This is the action that you want itris to perform with the record. At present, open is the only valid action but this may expand in the future.

Once the above 4 parameters are known, these can be used to construct the itris URL. The formatting is as follows:

itris:?dburl=<Database URL>&rt=<Record Type>&id=<Record Id>&act=open
⚠️ Data Formatting: When formatting the URL, it’s important to note that all values must be URL encoded. With the current parameters available, only the Database URL will require some additional formatting, although this could change in the future.

As an example, if I wanted to open applicant 234 on https://metrik-global.itris.app:1234 the URL would be formatted as follows:

itris:?dburl=https%3A%2F%2Fmetrik-global.itris.app%3A1234&rt=applicant&id=234&act=open

This itris link can be used in third party apps, and upon the first launch a user will be presented with the windows prompt to ask which application they would like to open it in.