Custom Fields Overview

Deputy supports the the ability to set Custom Fields against the timesheet and employee data types within a Deputy install. This allows you to set up to 128 custom fields that can be used to define items such as a question that you would like employees to answer at the end of the shift, or to store a piece of information which is relevant to an employees record that Deputy may not cover.

It should be noted that in the case of the employee resource within a Deputy install at the Premium level, these items do not show in the employee record UI and is only available for interaction via the API. Timesheet custom fields can be displayed within the Approve Timesheets area of Deputy.

Check the existing Custom Fields that have been setup in the Deputy install

The Custom Field Data stored in a Deputy install is shared across that Deputy install meaning that before adding any custom data from your application, you should check if any has already been setup. This ensures that you do not accidentally overwrite data fields which another application may have already set for the user.

You can check what Custom Fields are already present in a Deputy install with the following endpoint.

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v1/resource/CustomFieldData/QUERY'

This will return an array of all the custom fields already setup in the Deputy install.

[
    {
        "Id": 1,
        "System": "Employee",
        "F01": "1234",
        "Creator": 1,
        "Created": "2023-01-03T16:39:35+11:00",
        "Modified": "2023-01-03T16:39:35+11:00",
        "postman": "1234",
        "_DPMetaData": {
            "System": "CustomFieldData",
            "CreatorInfo": {
                "Id": 1,
                "DisplayName": "Simon Hutchinson",
                "EmployeeProfile": 1,
                "Employee": 1,
                "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_3ad576ba56df64c09cefdef831a3dc43.jpg?Expires=1673045445&Signature=KaEjCzEZ6OLV4ZGeGa-Eo771nQlW2VZpYJjbTNkMK-Q437KxZJqOE6Dey~wz33naidSu8qIL8RagoMjtOMZZd4TCfUFgVj7p2vTz8E0zIm4j~1Iw4GSm4-b16pBNnywi~hCH6h2QLG4zFOk7ghvGrNQo0D~jaH1uPB0c8xYFrnQ_&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ",
                "Pronouns": 0,
                "CustomPronouns": ""
            }
        }
    }
  ]

In this example, this Deputy install has a custom field already setup in the F01 custom field slot. This means we should avoid using F01 for our application.

📘

Empty Array

If the response to the above request is an empty array it means there is no custom fields setup within the Deputy install at that point in time.

Adding a custom field to the Employee Object

Adding a custom field to the employee object is handled with a POST request to the CustomFieldDataObject endpoint within the Employee resource.

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v1/resource/Employee/{EmployeeId}/CustomFieldDataObject

Sample Payload

{
    "System": "Employee", "F02": "5678"
}

In this particular example we are defining that we want to save this custom field against the Employee object. We are also defining that the custom field we want to add the data to is F02. There is 128 fields that can be used to store custom data against the employee object. These are F01 through to F128.

🚧

Ensure you have the correct custom field set in the payload

It is important to check that you are sending the correct Custom Field Fxxx number. There is no validation on this process meaning it is possible to overwrite existing data in other custom fields if the incorrect Fxxx number is sent by mistake.

Once you send the request, if it is successful you will get a response that includes a summary of the now added/updated custom field.

{
    "Id": 5,
    "System": "Employee",
    "F01": "5678",
    "Creator": 1,
    "Created": "2023-01-03T16:58:09+11:00",
    "Modified": "2023-01-03T16:58:09+11:00",
    "postman": "5678",
    "_DPMetaData": {
        "System": "CustomFieldData",
        "CreatorInfo": {
            "Id": 1,
            "DisplayName": "Simon Hutchinson",
            "EmployeeProfile": 1,
            "Employee": 1,
            "Photo": "",
            "Pronouns": 0,
            "CustomPronouns": ""
        }
    }
}

As you can see, in the example the id of 5 has been allocated to this new custom field and it has been saved against the Employee data type. For this employee when retrieving their employee record via the API instead of the CustomFieldData element having null it will return the integer of 5 as that is the CustomFieldData record associated to that employee now.

Adding a custom field to the Timesheet object

It is also possible to add 128 custom fields to the Timesheet object in each Deputy install. The process to do so is much the same as the employee object however there is a few differences to be aware of.

Sample Payload

{
  System: "Timesheet", 
  Name: "Leaving Late?", 
  ApiName:"leavinglate", 
  Type:8, 
  Validation: "nempty\nunq", 
  Valuelist:["Yes - Personal Reason,Yes - Manager Requested"],
  OperationUnit: [1] 
}

In this example we are adding a question to the timesheet approval screen which will ask the user if they are finishing their shift late. If they are, they then get the option to select from two predefined responses - "Yes - Personal Reason, "Yes - Manager Requested".

In the Timesheet payload its possible to define validation which needs to be taken into account when this field is being interacted with in the Deputy UI. This is defined in the Type data element.

The types which the Timesheet object supports is as follows:

1 - Text
2 - Number
3 - Large Text (Paragraph)
4 - Boolean/Checkbox
5 - List
6 - Multi List
8 - Boolean/ Checkbox with a comment field.

It is also possible to define whether this field needs to be mandatorily entered when approving the timesheet. This is handled with the Validation element.

For example if you include Validation: "nempty\nunq" this tells the Deputy system to validate that not only is the field not empty, but that it does not have to be unique. Another example such as "nempty\unq" would not allow the field to be empty, and when the data is entered, it must be unique to other data already in the system for that field.