This document intends to detail how to retrieve and update the main Employee Meta Data record details for a user within "MyWorkPal". It is already assumed the User is known and their MyWorkPal System ID stored/ready to use with all end points.


Pre-requisites:

API Client access

See How to create API Clients to see how to obtain API Client IDs and secrets


Permissions

The API Client requires all the base permissions to read tenants, users, and then permissions for read/write of the main Employee Details record details and Employee Details Meta Data. Only tenants that the API client has access to will be returned.


Environment "variables"


Within all examples:

{{url}} would be a full HTTPS URI such as https://webapi.myworkpal.co.uk

{{tenant_id}} is the unique tenant ID for the target user account

{{sub_domain_name}} is the unique tenant subdomain (lowercase text) for the target user account

{{system_id}} the unique SystemID for the target user 


Example request for a known user, for their "Employee" Meta Data:


{
   "tenantId":{{tenant_id}},
   "page":"EmployeeDetails",
   "ParentType":"User",
   "ParentId":{{system_id}}
}


POST    /api/admin/metadata/values/get



With the desired User System ID and Tenant ID to hand - this POST will return a representation of all tenant meta data groups and fields as configured by admin for the tenant. Meta data can have many groups, containing many fields, and each can have a value with a defined data type. Therefore to manage and maintain a User's metadata - there is no adding to or removing from the response data to create a SET request. One simply manages the value and ensures they match the type, and submits back new, modified, or removed values.


Full response structure, follows. The Tenant Meta Data contains "Group1" Containing "FieldA" and "FieldB", and "Group2" containing "FieldC"


{
   "metaDataCacheInvalidateTenantId":null,
   "tenantId":{{tenant_id}},
   "userAccountId":null,
   "page":"EmployeeDetails",
   "groups":[
      {
         "name":"Group1",
         "description":null,
         "orderPriority":0,
         "fields":[
            {
               "name":"FieldA",
               "description":"FieldA",
               "orderPriority":0,
               "type":0,
               "decimalPlaces":null,
               "dateViewType":null,
               "startDate":null,
               "endDate":null,
               "listItems":[
                  
               ],
               "lookupTableId":null,
               "lookupTableValueColumnName":null,
               "lookupTableTextColumnName":null,
               "lookupTableOrderColumnName":null,
               "lookupTableOrderColumnIsDescending":false,
               "fieldValue":{
                  "id":11445,
                  "fieldId":404,
                  "parentType":"User",
                  "parentId":{{system_id}},
                  "value":null
               },
               "reqForExtraReg":false,
               "hasPermissions":false,
               "userHasWritePermissions":true,
               "readOnlyPermissions":[
                  
               ],
               "readWritePermissions":[
                  
               ],
               "allowSetByExpressions":false,
               "displayType":0,
               "optionsLayout":0,
               "showOnClientScreen":false,
               "isMandatoryOnClientScreen":false,
               "id":404,
               "markForDelete":false
            },
            {
               "name":"FieldB",
               "description":null,
               "orderPriority":0,
               "type":3,
               "decimalPlaces":null,
               "dateViewType":0,
               "startDate":null,
               "endDate":null,
               "listItems":[
                  
               ],
               "lookupTableId":null,
               "lookupTableValueColumnName":null,
               "lookupTableTextColumnName":null,
               "lookupTableOrderColumnName":null,
               "lookupTableOrderColumnIsDescending":false,
               "fieldValue":{
                  "id":11446,
                  "fieldId":548,
                  "parentType":"User",
                  "parentId":{{system_id}},
                  "value":null
               },
               "reqForExtraReg":false,
               "hasPermissions":false,
               "userHasWritePermissions":true,
               "readOnlyPermissions":[
                  
               ],
               "readWritePermissions":[
                  
               ],
               "allowSetByExpressions":false,
               "displayType":0,
               "optionsLayout":0,
               "showOnClientScreen":false,
               "isMandatoryOnClientScreen":false,
               "id":548,
               "markForDelete":false
            }
         ],
         "id":48,
         "markForDelete":false
      },
      {
         "name":"Group2",
         "description":"Group2",
         "orderPriority":0,
         "fields":[
            {
               "name":"FieldC",
               "description":null,
               "orderPriority":0,
               "type":0,
               "decimalPlaces":null,
               "dateViewType":null,
               "startDate":null,
               "endDate":null,
               "listItems":[
                  
               ],
               "lookupTableId":null,
               "lookupTableValueColumnName":null,
               "lookupTableTextColumnName":null,
               "lookupTableOrderColumnName":null,
               "lookupTableOrderColumnIsDescending":false,
               "fieldValue":{
                  "id":11447,
                  "fieldId":462,
                  "parentType":"User",
                  "parentId":{{system_id}},
                  "value":null
               },
               "reqForExtraReg":false,
               "hasPermissions":false,
               "userHasWritePermissions":true,
               "readOnlyPermissions":[
                  
               ],
               "readWritePermissions":[
                  
               ],
               "allowSetByExpressions":false,
               "displayType":0,
               "optionsLayout":0,
               "showOnClientScreen":false,
               "isMandatoryOnClientScreen":false,
               "id":462,
               "markForDelete":false
            }
         ],
         "id":64,
         "markForDelete":false
      }
   ],
   "firstMetaDataPage":false,
   "addingTenantMetaData":false,
   "useSystemMetaData":false,
   "changeAudit":null
}

As with many MWP end points, various properties are sent - with the expectation being the response from the initial request forms the content for the POST to the SET.


The most important property is the one found at location: Groups => Field => FieldValue => Value

The value of this is dictated by the meta data field type found: Groups => Field => Type


The data can be reduced / simplified down to the following example, which contains "new" Values ready for submission:


{
   "tenantId":{{tenant_id}},
   "userAccountId":null,
   "page":"EmployeeDetails",
   "groups":[
      {
         "name":"Group1",
         "fields":[
            {
               "name":"FieldA",
               "type":0,
               "fieldValue":{
                  "id":11445,
                  "fieldId":404,
                  "parentType":"User",
                  "parentId":{{system_id}},
                  "value":"FIELD A VALUE"
               },
               "id":404
            },
            {
               "name":"FieldB",
               "type":3,
               "fieldValue":{
                  "id":11446,
                  "fieldId":548,
                  "parentType":"User",
                  "parentId":{{system_id}},
                  "value":"01/01/2025"
               },
               "id":548
            }
         ],
         "id":48
      },
      {
         "name":"Group2",
         "fields":[
            {
               "name":"FieldC",
               "type":0,
               "fieldValue":{
                  "id":11447,
                  "fieldId":462,
                  "parentType":"User",
                  "parentId":{{system_id}},
                  "value":"FIELD C VALUE"
               },
               "id":462
            }
         ],
         "id":64
      }
   ]
}


In this example, the original IDs are all kept - the "Field2" type = 3 dictates a value expectation of DateTime, whilst the other 2 in this example are type = 0, which is simple free text.


MetaData fields can be defined as several other data types, but these are the two primarily expected to be used at time of writing.


POST    /api/admin/metadata/values/set


With the appropriate Write permission, and a payload of JSON data born from the previously detailed GET, simply POST the data and await a response. If validation is successful and the request can be fulfilled, a simple empty 200 success status is sent back. If the request is invalid, a 400 bad request is returned.