User Defined Fields

In this section:

Intro

We are pleased to announce the beta availability of our User Defined Fields (UDF) API service. This new feature provides the capability to retrieve (GET) data from user-defined fields throughout the system. As this service is currently in a beta phase, we are making it available to a select group of customers on a case by case basis.

If you would like to discuss access to the UDF service, please send a request to: hrapi@iris.co.uk

Please be aware that as a beta service, the UDF API is still under active development.

This means you may encounter unexpected data consistency issues, and there may be changes to the service as we continue to refine and improve its functionality

Key Features

  • Access Custom Data: Retrieve UDF data from both standard system screens and your own custom-designed screens

    For example, if you have created a bespoke compliance screen in IRIS Cascade with bespoke fields or created custom fields and added them to the main screen, both are accessible through this new service (some limitation apply see below for more details)

  • Comprehensive Retrieval: The service supports retrieving UDFs in a cascading manner, ensuring you get all relevant data

  • Screen and Field Discovery:

    • Obtain a list of all screens containing UDFs

    • Retrieve a list of UDFs associated with individual users

Getting Started:

For detailed instructions on identifying and configuring UDFs and screens within IRIS Cascade, refer to Using the Screen Designer.

Important Beta Considerations

  • Read-Only Access (GET): Currently, this beta version only supports retrieving data (GET requests). We plan to add functionality for creating (POST) , updating (PUT), and deleting (DELETE) UDF data in a future release

  • Arrays - Currently there is no way to search for or filter by individual fields names due to a known bug with arrays an ODATA. As a workaround, download all data and filter outside the API

Glossary of Terms

  • Schema = Screen

  • Source Entity = Employee

The Endpoints Explained

UserDefinedFieldSchemas

This service is used to identify the screens that contain UD fields and their associated properties within IRIS Cascade. If a screen is not listed here, it means that the screen does not contain any UD fields.

  • /userdefinedfieldschemas – use this service to retrieve a list of ALL screens and their associated fields and properties within IRIS Cascade.

    • No mandatory ID’s required to call this

    • This responds with

      • ID = this is the schema / screen ID Example: "Id": "77076bce-cc88-409b-aca8-62175e6e9d7b",

      • When it was created / last modified in the AP. This is different to when it was created/last modified in IRIS Cascade– normally this is identified by the source system dates

      • Source entity = is always employee

      • Description = this field is obsolete and subject for removal

      • Source system ID = the screen name

      • Application meta data = is an array of data which defines the properties of the screen. For example, is it a list page or a tab page

    • CustomFields = is an array of all the UD fields on that screen and their properties

  • /userdefinedfields/schemas/{id} – use this service to retrieve a list of UD fields and properties within IRIS Cascade on an individual screen

UserDefinedFields

All 3 endpoints use the same model

  • /userdefinedfields/source/{sourceEntityId} - use this service to retrieve a list of ALL screens and ALL UD fields for 1 employee

    • Mandatory ID = sourceEntityId which is the API employee ID (GUID)

  • /userdefinedfields/schema/{schemaId} - use this service to retrieve a list of UD fields for 1 screen for ALL employees

    • Mandatory ID is the screen ID / schema ID found in the /userdefinedfieldschemas service

    • ID = is the UDF record ID for that employee

    • SourceEntityID = the employeeID from the Employee Service

    • SourceSystemID = the internal database ID Cascade uses

  • /userdefinedfields/{id} - use this service to retrieve a list of UD fields on 1 screen for 1 employee.

    • Mandatory ID = the UDF ID this is the unique ID for each employee record for each screen essentially taking the SchemaID + EmployeeID = UDF ID

Additional Notes

UserDefinedFields - Control Types

The data kept in IRIS Cascade relating to user defined fields and screens uses its own control type to determine the data.

This is reflected in the /userdefinedfieldschemas endpoint; within the CustomFields node. We have listed all relevant Control Types in IRIS Cascade you can use on the screens.

IRIS Cascade

Friendly Value

 Control Type Definition Additional Comments
Text (upto 50 chars) EDIT STRING Single line text
Text (upto 50 chars) SELECT STRING Uses system list value defined in'ValidList'property
Date DATE DATETIME  
Yes/No CHECK BIT Value will be 0 / 1 Or NULL / sometimes Uses system list value defined in'ValidList'property
Text (narrative > 50 chars) TEXTAREA STRING Multiline text
Number (Whole number e.g. 10) NUMERIC INT  
Decimal (e.g. 10.5) DECIMAL DECIMAL(16,2)  
  RADIO BIT Value will be 0 / 1 Or NULL / sometimes Uses system list value defined in'ValidList'property
Employee Picker EMPLOYEEPICKER STRING This ID is the Employee ID from the/employeeendpoint
Hierarchy Picker Field HIERARCHYPICKER STRING This is the Hierarchy ID from the/hierarchyendpoint
  LINKEDSELECT STRING Single line text, these values will be shown as strings
Currency Field (e.g. £10.50) CURRENCY DECIMAL The currency value, this field type always has 2 fields, 1 that contains the value and another that contains the currency ISO code. These fields are linked on field name, example: carallowanceUD =36000carallowanceUDcurrency ='GBP'
  HOURSMINUTES INT Raw value is stored as minutes. IRIS Cascade converts this into the value that's seen on screen, to achieve this take minutes value and divide by 60 to get hours / take minutes value and percent by 60 to get minute value combine the results as[HOUR : MINTUE]to get value as seen in Cascade.

The entries above that do not have a 'IRIS Cascade Friendly Value' are ones that the IRIS Cascade's support team must create. You cannot create these in the UI manually.

Which Endpoint to Use?

I want to retrieve a complete list of UD screens, fields and their associated properties = use the endpoint https://api.iris.co.uk/hr/v2/userdefinedfieldschemas

I want to retrieve a list of all UD fields for 1 screen and their associated properties = use the endpoint (with an OData filter)

https://api.iris.co.uk/hr/v2/userdefinedfieldschemas?$filter=sourcesystemid eq 'ScreenName' '

I know the API employee ID and I want to retrieve a list of all UD screens and fields for a single employee = use the endpoint https://api.iris.co.uk/hr/v2/userdefinedfields/source/{sourceEntityId}

I know the Screen ID and i want to retrieve a list of UD fields for all employees (where applicable). = use the endpoint https://api.iris.co.uk/hr/v2/userdefinedfields/schema/{schemaId}