From 7530ec3d64fb42e60b371755934be49667a57893 Mon Sep 17 00:00:00 2001 From: "Nathan.Lawson" Date: Fri, 31 Jan 2025 11:17:51 -0700 Subject: [PATCH 1/8] [ILX-50471] Add documentation for the User Management API --- source/includes/_user-mgmt-api.md | 3 + source/includes/user-mgmt/get-api.md | 3 + source/includes/user-mgmt/group-membership.md | 3 + source/includes/user-mgmt/post-patch-api.md | 137 ++++++++++++++++++ 4 files changed, 146 insertions(+) create mode 100644 source/includes/_user-mgmt-api.md create mode 100644 source/includes/user-mgmt/get-api.md create mode 100644 source/includes/user-mgmt/group-membership.md create mode 100644 source/includes/user-mgmt/post-patch-api.md diff --git a/source/includes/_user-mgmt-api.md b/source/includes/_user-mgmt-api.md new file mode 100644 index 00000000000..8ca79fd2e4e --- /dev/null +++ b/source/includes/_user-mgmt-api.md @@ -0,0 +1,3 @@ +# USER MANAGEMENT API + +The V6 User Management API gives you the ability to simultaneously manage Employee and User acccess in V6. diff --git a/source/includes/user-mgmt/get-api.md b/source/includes/user-mgmt/get-api.md new file mode 100644 index 00000000000..35d424acfd9 --- /dev/null +++ b/source/includes/user-mgmt/get-api.md @@ -0,0 +1,3 @@ +## Retrieve Data + +This section outlines the blah blah blah diff --git a/source/includes/user-mgmt/group-membership.md b/source/includes/user-mgmt/group-membership.md new file mode 100644 index 00000000000..ffe2dda8b97 --- /dev/null +++ b/source/includes/user-mgmt/group-membership.md @@ -0,0 +1,3 @@ +## Employee Group Membership Management + +This section outlines the blah blah blah diff --git a/source/includes/user-mgmt/post-patch-api.md b/source/includes/user-mgmt/post-patch-api.md new file mode 100644 index 00000000000..91be8046b8c --- /dev/null +++ b/source/includes/user-mgmt/post-patch-api.md @@ -0,0 +1,137 @@ +## Add or Modify Data + +## Field Reference + +### Employee Fields + +Property | Description +--------- | ----------- +Flag|TBD +EmployeeNumber*|TBD +HomeLocationCode*|TBD +Prefix|TBD +FirstName*|TBD +LastName*|TBD +MiddleName|TBD +DisplayName|TBD +Suffix|TBD +Email|TBD +IsSupervisor|TBD +EmployeeType|TBD +Date_Of_Hire|TBD +SupervisorNumber|TBD +PositionTitle|TBD +Notes|TBD +Contractor|TBD +Company|TBD +ContractorName|TBD +ContractExpiry|TBD +InsuranceExpiry|TBD +ContractorNotes|TBD +StreetAddress|TBD +City|TBD +State|TBD +ZipCode|TBD +Gender|TBD +Date_Of_Birth|TBD +SSN|TBD +EmergencyContact|TBD +EmergencyPhone|TBD +PersonResponsible|TBD +PhoneNumber|TBD +HourlyWage|TBD +JobCode|TBD +WorkStatus|TBD +Groups|TBD + +### User Fields + +Property | Description +--------- | ----------- +UserId*|TBD +IsLocked|TBD +Password|TBD +SecondaryPassword|TBD +ForcePasswordChange|TBD +LoginLocationCode*|TBD +TimeZone|TBD +LicenseType*|TBD +CultureName|TBD +LongDate|TBD +LongTime|TBD +ShortDate|TBD +ShortTime|TBD + +> Example response with record metadata + +```json +{ + // IUserMgmtSettings (EDIS Settings) Fields + "SendEmail": true, + "IgnoreUserAccess": false, + + // Employee Fields + "Flag": "AAA", // Must be A or I + "EmployeeNumber": "0011144", // Required, checked for uniqueness + "HomeLocationCode": "001", // Required, checked for existence + "Prefix": "pre", + "FirstName": "AAAJohn", // Required + "LastName": "Doe", // Required + "MiddleName": "Joe", + "DisplayName": "John Doe44", // If blank, will be set as "{FirstName} {LastName}" + "Suffix": "suf", + "Email": "john.doe@intelex.com", + "IsSupervisor": "Y", // Must be Y or N + "EmployeeType": "Hourly", // Converted to EmployeeTypeId + "Date_Of_Hire": "2019-11-25", + "SupervisorNumber": "001", // Checked for existence + "PositionTitle": "Line Worker", + "Notes": "dfghdfghdfg", + "Contractor": "Y", // Must be Y or N + "Company": "Intelex", + "ContractorName": "Sears", + "ContractExpiry": "2026-12-30", + "InsuranceExpiry": "2026-12-31", + "ContractorNotes": "zdgsdf", + "StreetAddress": "5613 DTC Pkwy Suite 320", + "City": "Greenwood Village", + "State": "Colorado", + "ZipCode": "80111", + "Gender": "M", + "Date_Of_Birth": "1999-06-23", + "SSN": "111-11-1111", + "EmergencyContact": "Jane Doe", + "EmergencyPhone": "123-456-7890", + "PersonResponsible": 1, // Not currently used + "PhoneNumber": "111-111-1111", + "HourlyWage": "25", + "JobCode": "jc12", + "WorkStatus": "full time", + + // User Fields + "UserId": "jdoe41", // Required if user access is requested + "IsLocked": false, + "Password": "1234", + "SecondaryPassword": "5678", + "ForcePasswordChange": false, + "LoginLocationCode": "001", // Required if user access is requested + "TimeZone": "Eastern Standard Time", // Checked for existence + "LicenseType": "Full Access", // Required if user access is requested. Checked for existence + "CultureName": "English (United States)", + "LongDate": "", + "LongTime": "", + "ShortDate": "", + "ShortTime": "", + + "Groups": "Claims Administrator(01E4C606-2F03-4044-B6B1-079AE288D82A);7F50AC4D-93F4-4DF9-90AF-00D7DF663720", + +} +``` + +## Add Data + +This section outlines the blah blah blah + +## Modify Data + +This section outlines the blah blah blah From 39710e483a2c6f0c0ea01df83d57208d6abb712f Mon Sep 17 00:00:00 2001 From: "Nathan.Lawson" Date: Fri, 31 Jan 2025 15:38:16 -0700 Subject: [PATCH 2/8] Progress commit --- source/includes/user-mgmt/post-patch-api.md | 519 +++++++++++++++++--- source/index.html.md | 8 +- 2 files changed, 467 insertions(+), 60 deletions(-) diff --git a/source/includes/user-mgmt/post-patch-api.md b/source/includes/user-mgmt/post-patch-api.md index 91be8046b8c..f91c1a05a6c 100644 --- a/source/includes/user-mgmt/post-patch-api.md +++ b/source/includes/user-mgmt/post-patch-api.md @@ -1,68 +1,473 @@ ## Add or Modify Data -## Field Reference +### Payload Validation + +Fields in the payload will be checked for validity befor creating the employee and user records. + +Some validations for Create (POST) include: +- Required fields that are not included in the payload +- Invalid external identifiers that do not exist (E.g. SupervisorNumber, LoginLocationCode) +- Duplicate primary key identifiers (E.g. duplicate EmployeeNumber or DisplayName) + +> Example POST response with validation errors + +```json +{ + "error": { + "messages": [ + "There is an existing employee with the same employee number." + ] + } +} +``` + +Some validations for Update (PATCH) include: +- Required identifier fields (Id, EmployeeNumber) not included in the request + +> Example PATCH response with validation errors + +```json +{ + "error": { + "messages": [ + "There is an existing employee with the same employee number." + ] + } +} +``` + +### Payload Field Reference + +#### Settings Flags + +Settings flags are payload fields that configure the behavior of the user management API request. + +Some settings flags may be ignored if the flag is not relevant to the request type. For example, RevokeUserAccess is only applicable to an existing user, so is only applicable in a update (PATCH) request. + +All flags default to false unless otherwise noted. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyDescription
IgnoreUserAccess + Skips user access creation. Employee record will still be created. +
SendEmail +
  • Send a password reset email upon successful user creation.
    • +
  • Only respected if user access is requested. I.e. IgnoreUserAccess = false
    • +
    RevokeUserAccess +
  • Existing users only. Only respected if user access is requested.
    • +
  • Revokes access for the specified user.
    • +
  • +
    ArchiveIfTasksAssigned +
  • Existing users only. Only respected if user access is requested.
    • +
  • +
    DoNotAddGroupAssignments +
  • Existing employees only.
    • +
  • Do not assign employee membership to the groups specified in the Groups field.
    • +
    RemoveFromUnlistedGroups +
  • Existing employees only
    • +
  • Remove employee membership from any previously assigned groups that are not specified in the Groups field.
    • +
  • This field is still respected if DoNotAddGroupAssignments is set.
    • +
    ### Employee Fields -Property | Description ---------- | ----------- -Flag|TBD -EmployeeNumber*|TBD -HomeLocationCode*|TBD -Prefix|TBD -FirstName*|TBD -LastName*|TBD -MiddleName|TBD -DisplayName|TBD -Suffix|TBD -Email|TBD -IsSupervisor|TBD -EmployeeType|TBD -Date_Of_Hire|TBD -SupervisorNumber|TBD -PositionTitle|TBD -Notes|TBD -Contractor|TBD -Company|TBD -ContractorName|TBD -ContractExpiry|TBD -InsuranceExpiry|TBD -ContractorNotes|TBD -StreetAddress|TBD -City|TBD -State|TBD -ZipCode|TBD -Gender|TBD -Date_Of_Birth|TBD -SSN|TBD -EmergencyContact|TBD -EmergencyPhone|TBD -PersonResponsible|TBD -PhoneNumber|TBD -HourlyWage|TBD -JobCode|TBD -WorkStatus|TBD -Groups|TBD +Payload fields that are associated with the employee record to be created or updated. Properties denoted with a * are required and must be included in the payload. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PropertyDescription
    Flag +
  • Indicates whether employe should be archived in the system:
    • +
      +
    • A = Active employee (default)
      • +
    • I = Inactive (archived) employee
      • +
    +
  • Archiving an an employee will also remove the associated user's access, if available.
    • +
    EmployeeNumber* + Primary Key; Unique identifier of employee. +
    HomeLocationCode* +
  • Location Code of the home location of this employee.
    • +
  • This is the Location field on the employee profile.
    • +
    Prefix + Prefix of employee (e.g., Mr., Mrs., Ms.) +
    FirstName* + First name of employee. +
    LastName* + Last name of employee. +
    MiddleName + Middle name of employee +
    DisplayName + Last name of employee. +
    Suffix + Suffix of employee (e.g., Jr., Sr.) +
    Email + Email address of employee. +
    IsSupervisor + Indicates whether employee has direct reports or not. +
    EmployeeType + Type of employee. +
    Date_Of_Hire +
  • Date of hire of employee.
    • +
  • Please speak with your consultant to confirm the date format for your subdomain.
    • +
    SupervisorNumber + Employee Number of supervisor of employee. +
    PositionTitle + Job title of employee. +
    Notes + Open text field found in employee profile. +
    Contractor + Indicates whether employee is a contractor. +
    Company + Company name of employee. +
    ContractorName + Contractor company name of employee. +
    ContractExpiry +
  • Contract expiration date of employee.
    • +
  • Please speak with your consultant to confirm the date format for your subdomain.
    • +
    InsuranceExpiry +
  • Insurance expiration date of employee.
    • +
  • Please speak with your consultant to confirm the date format for your subdomain.
    • +
    ContractorNotes + Open text field found in employee profile. +
    StreetAddress + Street address of employee. +
    City + City of employee. +
    State + State of employee. +
    ZipCode + Zip code (or postal code) of employee. +
    Gender + Gender of employee. +
    Date_Of_Birth +
  • Date of birth of employee.
    • +
  • Please speak with your consultant to confirm the date format for your subdomain.
    • +
    SSN + Social security number of employee. +
    EmergencyContact + Emergency contact information of employee. +
    EmergencyPhone + Emergency phone number of employee. +
    PersonResponsible +
  • Mandatory for Document Control (all platform versions) and Reassign Task (6.2.5 or lower) feature.
    • +
  • For clients on 6.2.5 or lower, it is recommended to default this value to 1, if not being used.
    • +
  • See V6 System Administrator User Guide on Intelex Exchange for additional details.
    • +
  • For New Employee:
    • +
      +
    • 1: Add to Home Locations & all Locations below
      • +
    • 2: Add to Home Location only
      • +
    • 3: Do not add to Person Responsible List (PRL)
      • +
    +
  • For Existing Employee:
    • +
      +
    • 1: Clear PRL for this employee then add employee to Home Location & all Locations below
      • +
    • 2: Clear PRL for this employee then add employee to Home Location only (does not keep manually added Locations)
      • +
    • 3: Clear PRL for this employee (do not add)
      • +
    • 4: Leave PRL as is (no change)
      • +
    • 5: Replace current Home Location with new Home Location (and keep manually added locations)
      • +
    +
    PhoneNumber + Phone number of employee. +
    HourlyWage + Hourly wage of employee. +
    JobCode + Job Code for employee. +
    WorkStatus + [Legal] Work status of employee. +
    Groups +
  • Semicolon (;) delimited list of elements that this employee is a member of (excluding Everyone group).
    • +
  • Each element can be the Caption or GUID of any Group or Location Role.
    • +
  • Groups includes Security Groups, Roles, Location Roles and Training Workgroups.
    • +
  • If an element is invalid, then the processing of this particular element is skipped; other elements for the employee are not skipped.
    • +
  • Notation for Location Role: RoleCaption(LocationCodeOrGUID)
    • +
    ### User Fields -Property | Description ---------- | ----------- -UserId*|TBD -IsLocked|TBD -Password|TBD -SecondaryPassword|TBD -ForcePasswordChange|TBD -LoginLocationCode*|TBD -TimeZone|TBD -LicenseType*|TBD -CultureName|TBD -LongDate|TBD -LongTime|TBD -ShortDate|TBD -ShortTime|TBD - -> Example response with record metadata +Payload fields that are associated with the user record to be created or updated if requested (IgnoreUserAccess = false). If user access is requested, properties denoted with a * are required and must be included in the payload. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PropertyDescription
    UserId* +
  • Used by employee to login to the Intelex system; must be unique.
    • +
  • Recommendation: Email address of employee.
    • +
  • Set to email ID for SSO.
    • +
    IsLocked + Locks or unlocks the user +
    Password +
  • Password that employee users to log in to the Intelex system.
    • +
  • Ignores Account Policy rules.
    • +
  • Password is not required if implementing SSO.
    • +
    SecondaryPassword +
  • For Electronic Signatures only.
    • +
  • Stores a secondary password that can be used by electronic signatures.
    • +
    ForcePasswordChange +
  • If set to true, user will be forced to change his/her password upon his/her next successful log in.
    • +
  • User access updated through EDIS will leave Force Password Change untouched if it the flag is anything other than the characters mentioned above.
    • +
  • 1 = User will be forced to change his/her password on next log in (also accepts values "Y", "y", "T", "t").
    • +
  • 0 (or null) = User will NOT be forced to change his/her password (also accepts values "N", "n", "F", "f").
    • +
    LoginLocationCode* +
  • Location Code of the login location of this employee.
    • +
  • This is the Logon Location field on the user profile.
    • +
    TimeZone +
  • Time Zone for the User. In the EDIS template the user can select the Time Zone from a select control, in the default template downloaded from the Data Import user have to enter the value manually.
    • +
  • Example: (UTC-05:00) Eastern Time (US & Canada)
    • +
    LicenseType* +
  • Must map correctly to SecurityGroupName column:
    • +
      +
    • IF (SecurityGroupName) Limited Access THEN SET (LicenseType) TO Concurrent Access
      • +
    • IF (SecurityGroupName) Supervisor Access THEN SET (LicenseType) TO Concurrent Access
      • +
    • IF (SecurityGroupName) Full Access THEN SET (LicenseType) TO Full Access
      • +
    • IF (SecurityGroupName) System Administrator THEN SET (LicenseType) TO System Administrator
      • +
    +
  • Identifies specific V6 license type assigned in License Type field in user profile.
    • +
    CultureName +
  • For clients who have purchased additional languages.
    • +
  • Identifies culture assigned in Culture field in user profile. If the value in this staging table is "Automatic" will set to "Determine Automatically".
    • +
  • Inactive cultures won't be assigned to a user.
    • +
    LongDate + d, dd = day; ddd, dddd = day of week; M, MM = month; yy, yyyy = year +
    LongTime + h, hh = hour (12-hour format); H, HH = hour (24-hour format); m = minutes; s = seconds; tt = A.M. or P.M. +
    ShortDate + d, dd = day; ddd, dddd = day of week; M, MM = month; yy, yyyy = year +
    ShortTime + h, hh = hour (12-hour format); H, HH = hour (24-hour format); m = minutes; s = seconds; tt = A.M. or P.M. +
    + +> Example request body payload ```json { diff --git a/source/index.html.md b/source/index.html.md index 4f18320125f..7494f2fd758 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -4,7 +4,7 @@ title: Intelex API Reference language_tabs: - javascript: JavaScript - csharp: C# - + includes: - api-reference - object-data-api @@ -14,9 +14,11 @@ includes: - acts/get_api - acts/post_api - acts/delete_api + - user-mgmt-api + - user-mgmt/get-api + - user-mgmt/post-patch-api + - user-mgmt/group-membership - dev-support - search: true --- - From 1bc0b995e8f2f7096b4c0ab4f87d47d71a233b3b Mon Sep 17 00:00:00 2001 From: "Nathan.Lawson" Date: Mon, 3 Feb 2025 13:01:33 -0700 Subject: [PATCH 3/8] First draft --- source/includes/_user-mgmt-api.md | 4 +- source/includes/user-mgmt/group-membership.md | 3 - source/includes/user-mgmt/post-patch-api.md | 384 +++++++++++++----- source/index.html.md | 1 - 4 files changed, 282 insertions(+), 110 deletions(-) delete mode 100644 source/includes/user-mgmt/group-membership.md diff --git a/source/includes/_user-mgmt-api.md b/source/includes/_user-mgmt-api.md index 8ca79fd2e4e..13a99aa1c45 100644 --- a/source/includes/_user-mgmt-api.md +++ b/source/includes/_user-mgmt-api.md @@ -1,3 +1,5 @@ # USER MANAGEMENT API -The V6 User Management API gives you the ability to simultaneously manage Employee and User acccess in V6. +The User Management API provides the ability to externally manage employee and user acccess in Intelex. + +Functionality for this endpoint includes employee and user [creation](#add-data) and [modification](#modify-data) with the ability to archive employees and revoke user access. Requests may also optionally [assign and revoke group membership](#group-membership) to the employee. diff --git a/source/includes/user-mgmt/group-membership.md b/source/includes/user-mgmt/group-membership.md deleted file mode 100644 index ffe2dda8b97..00000000000 --- a/source/includes/user-mgmt/group-membership.md +++ /dev/null @@ -1,3 +0,0 @@ -## Employee Group Membership Management - -This section outlines the blah blah blah diff --git a/source/includes/user-mgmt/post-patch-api.md b/source/includes/user-mgmt/post-patch-api.md index f91c1a05a6c..50297e6a14d 100644 --- a/source/includes/user-mgmt/post-patch-api.md +++ b/source/includes/user-mgmt/post-patch-api.md @@ -1,50 +1,132 @@ ## Add or Modify Data -### Payload Validation +> User Management API Endpoint - replace **intelex_object** with the system name of your object -Fields in the payload will be checked for validity befor creating the employee and user records. +``` +https://intelex_url/api/v2/EmployeeUserAccess +``` -Some validations for Create (POST) include: -- Required fields that are not included in the payload -- Invalid external identifiers that do not exist (E.g. SupervisorNumber, LoginLocationCode) -- Duplicate primary key identifiers (E.g. duplicate EmployeeNumber or DisplayName) +### Add Data -> Example POST response with validation errors +#### POST /EmployeeUserAccess -```json -{ - "error": { - "messages": [ - "There is an existing employee with the same employee number." - ] - } -} +##### Body Parameters + +| Parameter | Description | +| ---------- | ---------------------------------------------------------------------------------------------------------------- | +| field_name | The value you want to set for an employee or user field. Replace _field_name_ with the name of the employee or user field | + +See [Request Payload Field Reference](#request-payload-field-reference) for detailed field information. + +> Example Request + +```javascript +var request = require("request"); + +var options = { + method: 'POST', + url: 'https://intelex_url/api/v2/EmployeeUserAccess', + headers: { 'content-type': 'application/json' }, + body: + { + "EmployeeNumber": "001", + "HomeLocationCode": "001", + "FirstName": "John", + "LastName": "Doe", + "UserId": "jdoe", + "LoginLocationCode": "001", + "LicenseType": "Full Access" + } +}; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); ``` -Some validations for Update (PATCH) include: -- Required identifier fields (Id, EmployeeNumber) not included in the request +```csharp +var client = new RestClient("https://intelex_url/api/v2/EmployeeUserAccess"); +var request = new RestRequest(Method.POST); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\r\n \"EmployeeNumber\": \"001\",\r\n \"HomeLocationCode\": \"001\",\r\n \"FirstName\": \"John\",\r\n \"LastName\": \"Doe\",\r\n \"UserId\": \"jdoe\",\r\n \"LoginLocationCode\": \"001\",\r\n \"LicenseType\": \"Full Access\"\r\n}", ParameterType.RequestBody); +IRestResponse response = client.Execute(request); +``` -> Example PATCH response with validation errors +A succesful POST to the EmployeeUserAccess endpoint will respond with a 201 Created response code and a json body containing the Id for the created employee and user records. + +> Example of successful create (POST) response ```json { - "error": { - "messages": [ - "There is an existing employee with the same employee number." - ] - } + "Id": "43d1b046-156a-4715-bf96-10f71690a528" } ``` -### Payload Field Reference +### Modify Data + +#### PATCH /EmployeeUserAccess({id}) + +##### URL Parameters + +| Parameter | Description | +| ---------------------- | -------------------------------------------------- | +| employee_id _(optional)_ | The Intelex UID of the employee/user being updated | + +NOTE: You may also provide a valid Id or EmployeeNumber in the payload as the identifier used to update the record. + +##### Body Parameters + +| Parameter | Description | +| ---------- | ---------------------------------------------------------------------------------------------------------------- | +| field_name | The value you want to set for and employee or user field. Replace _field_name_ with the name of the employee or user field | + +See [Request Payload Field Reference](#request-payload-field-reference) for detailed field information. + +> Example Request + +```javascript +var request = require("request"); + +var options = { + method: 'PATCH', + url: 'https://intelex_url/api/v2/EmployeeUserAccess', + headers: { 'content-type': 'application/json' }, + body: + { + "EmployeeNumber": "001", + "FirstName": "Jon", + "IsLocked": true + } +}; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); +}); +``` + +```csharp +var client = new RestClient("https://intelex_url/api/v2/EmployeeUserAccess"); +var request = new RestRequest(Method.POST); +request.AddHeader("content-type", "application/json"); +request.AddParameter("application/json", "{\r\n \"EmployeeNumber\": \"001\",\r\n \"FirstName\": \"Jon\",\r\n \"IsLocked\": true\r\n}", ParameterType.RequestBody); +IRestResponse response = client.Execute(request); +``` + +A succesful PATCH to the EmployeeUserAccess endpoint will respond with a 204 No Content response code. + +### Request Payload Field Reference #### Settings Flags -Settings flags are payload fields that configure the behavior of the user management API request. +Settings flags are payload fields that configure various behaviors of the user management API request. -Some settings flags may be ignored if the flag is not relevant to the request type. For example, RevokeUserAccess is only applicable to an existing user, so is only applicable in a update (PATCH) request. +Some settings flags may be ignored if the flag is not relevant to the request type. For example, RevokeUserAccess is only applicable to an existing user, so is only applicable in an update (PATCH) request. -All flags default to false unless otherwise noted. +All flags default to false unless otherwise noted. @@ -96,9 +178,11 @@ All flags default to false unless otherwise noted.
    -### Employee Fields +#### Employee Fields -Payload fields that are associated with the employee record to be created or updated. Properties denoted with a * are required and must be included in the payload. +Payload fields that are associated with the employee record to be created or updated. + +Properties denoted with a \* are required and must be included in the payload. @@ -174,13 +258,15 @@ Payload fields that are associated with the employee record to be created or upd @@ -211,7 +297,8 @@ Payload fields that are associated with the employee record to be created or upd @@ -359,9 +446,11 @@ Payload fields that are associated with the employee record to be created or upd
    IsSupervisor - Indicates whether employee has direct reports or not. +
  • Indicates whether employee has direct reports or not.
    • +
  • Valid values are Y or N
    		•
    EmployeeType - Type of employee. +
  • Type of Employee.
    • +
  • Must be the Name of a valid SysEmployeeType record.
    		•
    Contractor - Indicates whether employee is a contractor. +
  • Indicates whether employee is a contractor.
    • +
  • Valid values are Y or N
    		•
    -### User Fields +#### User Fields + +Payload fields that are associated with the user record to be created or updated if requested (IgnoreUserAccess = false). -Payload fields that are associated with the user record to be created or updated if requested (IgnoreUserAccess = false). If user access is requested, properties denoted with a * are required and must be included in the payload. +If user access is requested, properties denoted with a \* are required and must be included in the payload. @@ -416,28 +505,28 @@ Payload fields that are associated with the user record to be created or updated @@ -467,76 +556,161 @@ Payload fields that are associated with the user record to be created or updated
    TimeZone -
  • Time Zone for the User. In the EDIS template the user can select the Time Zone from a select control, in the default template downloaded from the Data Import user have to enter the value manually.
    • +
  • Time Zone for the User.
  • Example: (UTC-05:00) Eastern Time (US & Canada)
    		•
    LicenseType* -
  • Must map correctly to SecurityGroupName column:
    • +
  • Identifies specific V6 license type assigned in License Type field in user profile.
    • +
  • Valid values are:
      • -
    • IF (SecurityGroupName) Limited Access THEN SET (LicenseType) TO Concurrent Access
      • -
    • IF (SecurityGroupName) Supervisor Access THEN SET (LicenseType) TO Concurrent Access
      • -
    • IF (SecurityGroupName) Full Access THEN SET (LicenseType) TO Full Access
      • -
    • IF (SecurityGroupName) System Administrator THEN SET (LicenseType) TO System Administrator
      • +
    • Concurrent Access
      • +
    • Full Access
      • +
    • System Administrator
    -
  • Identifies specific V6 license type assigned in License Type field in user profile.
    		•
    CultureName
  • For clients who have purchased additional languages.
    • -
  • Identifies culture assigned in Culture field in user profile. If the value in this staging table is "Automatic" will set to "Determine Automatically".
    • +
  • Identifies culture assigned in Culture field in user profile.
    • +
  • "Automatic" will set to "Determine Automatically".
  • Inactive cultures won't be assigned to a user.
    		•
    -> Example request body payload +> Full example request body payload ```json { - // IUserMgmtSettings (EDIS Settings) Fields - "SendEmail": true, - "IgnoreUserAccess": false, - - // Employee Fields - "Flag": "AAA", // Must be A or I - "EmployeeNumber": "0011144", // Required, checked for uniqueness - "HomeLocationCode": "001", // Required, checked for existence - "Prefix": "pre", - "FirstName": "AAAJohn", // Required - "LastName": "Doe", // Required - "MiddleName": "Joe", - "DisplayName": "John Doe44", // If blank, will be set as "{FirstName} {LastName}" - "Suffix": "suf", - "Email": "john.doe@intelex.com", - "IsSupervisor": "Y", // Must be Y or N - "EmployeeType": "Hourly", // Converted to EmployeeTypeId - "Date_Of_Hire": "2019-11-25", - "SupervisorNumber": "001", // Checked for existence - "PositionTitle": "Line Worker", - "Notes": "dfghdfghdfg", - "Contractor": "Y", // Must be Y or N - "Company": "Intelex", - "ContractorName": "Sears", - "ContractExpiry": "2026-12-30", - "InsuranceExpiry": "2026-12-31", - "ContractorNotes": "zdgsdf", - "StreetAddress": "5613 DTC Pkwy Suite 320", - "City": "Greenwood Village", - "State": "Colorado", - "ZipCode": "80111", - "Gender": "M", - "Date_Of_Birth": "1999-06-23", - "SSN": "111-11-1111", - "EmergencyContact": "Jane Doe", - "EmergencyPhone": "123-456-7890", - "PersonResponsible": 1, // Not currently used - "PhoneNumber": "111-111-1111", - "HourlyWage": "25", - "JobCode": "jc12", - "WorkStatus": "full time", - - // User Fields - "UserId": "jdoe41", // Required if user access is requested - "IsLocked": false, - "Password": "1234", - "SecondaryPassword": "5678", - "ForcePasswordChange": false, - "LoginLocationCode": "001", // Required if user access is requested - "TimeZone": "Eastern Standard Time", // Checked for existence - "LicenseType": "Full Access", // Required if user access is requested. Checked for existence - "CultureName": "English (United States)", - "LongDate": "", - "LongTime": "", - "ShortDate": "", - "ShortTime": "", - - "Groups": "Claims Administrator(01E4C606-2F03-4044-B6B1-079AE288D82A);7F50AC4D-93F4-4DF9-90AF-00D7DF663720", + "SendEmail": true, + "IgnoreUserAccess": false, + "Flag": "A", + "EmployeeNumber": "001", + "HomeLocationCode": "001", + "Prefix": "Mr.", + "FirstName": "John", + "LastName": "Doe", + "MiddleName": "Joe", + "DisplayName": "John Doe", + "Suffix": "III", + "Email": "john.doe@intelex.com", + "IsSupervisor": "Y", + "EmployeeType": "Hourly", + "Date_Of_Hire": "2019-11-25", + "SupervisorNumber": "001", + "PositionTitle": "Line Worker", + "Notes": "Notes for me", + "Contractor": "Y", + "Company": "Intelex", + "ContractorName": "Sears", + "ContractExpiry": "2026-12-30", + "InsuranceExpiry": "2026-12-31", + "ContractorNotes": "Notes for the Contractor", + "StreetAddress": "5613 DTC Pkwy Suite 320", + "City": "Greenwood Village", + "State": "Colorado", + "ZipCode": "80111", + "Gender": "M", + "Date_Of_Birth": "1999-06-23", + "SSN": "111-11-1111", + "EmergencyContact": "Jane Doe", + "EmergencyPhone": "123-456-7890", + "PersonResponsible": 1, + "PhoneNumber": "111-111-1111", + "HourlyWage": "25", + "JobCode": "jc12", + "WorkStatus": "full time", + + "UserId": "jdoe", + "IsLocked": false, + "Password": "1234", + "SecondaryPassword": "5678", + "ForcePasswordChange": false, + "LoginLocationCode": "001", + "TimeZone": "Eastern Standard Time", + "LicenseType": "Full Access", + "CultureName": "English (United States)", + "LongDate": "", + "LongTime": "", + "ShortDate": "", + "ShortTime": "", + + "Groups": "Claims Administrator(01E4C606-2F03-4044-B6B1-079AE288D82A);7F50AC4D-93F4-4DF9-90AF-00D7DF663720" +} +``` + +### Payload Validation + +Fields in the payload will be checked for validity before creating or updating the employee and user records. + +#### Create (POST) Payload Validation + +Example payload validations for creation include: + +
      +
    • Required fields that are not included in the payload
      • +
    • Invalid external identifiers that do not exist (E.g. SupervisorNumber, LoginLocationCode)
      • +
    • Duplicate primary key identifiers (E.g. EmployeeNumber, DisplayName)
      • +
    + +#### Update (PATCH) Payload Validation + +Example payload validations for modification include: + +
      +
    • Required identifier fields (Id, EmployeeNumber) not included in the request
      • +
    • Required fields that are empty ("") in the payload
      • +
    • Invalid external identifiers that do not exist (E.g. SupervisorNumber, LoginLocationCode)
      • +
    • Duplicate primary key identifiers (E.g. EmployeeNumber, DisplayName)
      • +
    + +> Example response with validation errors + +```json +{ + "error": { + "messages": [ + "Cannot create employee - Invalid value for IsSupervisor. Please use either 'Y' or 'N'", + "There is an existing employee with the same employee number.", + "Home location with code 001 is not found." + ] + } } ``` -## Add Data +### Group Membership + +Group membership for an employee may also be managed via the User Management API with use of the Groups field. The Groups field expects a semi-colon delimited list of groups in one of the following formats: +
      +
    • GroupId
      • +
    • GroupName
      • +
    • RoleId(LocationId) (for a Location Role)
      • +
    • RoleId(LocationCode) (for a Location Role)
      • +
    • RoleName(LocationId) (for a Location Role)
      • +
    • RoleName(LocationCode) (for a Location Role)
      • +
    -This section outlines the blah blah blah +"Groups" include Security Groups, Roles, Location Roles and Training Workgroups, or any object that inherits from the Group Entity. -## Modify Data +#### Roles and Location Roles -This section outlines the blah blah blah +If an entry is a role and no location is defined for the entry (E.g. As RoleId(LocationId)), a location role will be assigned using the LoginLocationCode value. If LoginLocationCode is invalid or not present in the payload, the Role will be assigned without a location. + +Roles with AllowManySubjects set to false will unassign any existing members from the role before assigning membership to the target employee. + +#### Group Membership Settings + +See [Settings Flags](#settings-flags) for details on DoNotAddGroupAssignments and RemoveFromUnlistedGroups fields. + +#### Group Validation + +Groups are validated before membership is assigned. If any validations fail, error messages will be returned in the response. + +Example group validations include: +
      +
    • Group Id or Name does not exist.
      • +
    • Group for a LocationRole (GroupId(LocationId), in this case GroupId) does not exist.
      • +
    • Group Id or Name for a location role (Role(Location)), is not a Role. E.g. If you try to use the ID of a SysSecurityGroup as a role in a location role, the parsing will fail.
      • +
    • Location code does not exist or is invalid.
      • +
    + +> Example of a payload with Groups + +```json +{ + "Groups": "7F50AC4D-93F4-4DF9-90AF-00D7DF663720;Insurance;36D48405-36EA-42C8-B11B-CA50DAB377DD(01E4C606-2F03-4044-B6B1-079AE288D82A);BD5797DD-D015-429C-89E6-1A79C3EB7B79(056);Claims Administrator(01E4C606-2F03-4044-B6B1-079AE288D82A);Claims Administrator(001)" +} +``` + +> Example response with group validation errors + +```json +{ + "error": { + "messages": [ + "The Location Role 'Role123(Loc123)' is invalid. Please ensure that the Role (Role123) is the Name or ID of a valid and existing Role.", + "Group '36D48405-36EA-42C8-B11B-CA50DAB377DD' is invalid. Group with ID '36D48405-36EA-42C8-B11B-CA50DAB377DD' does not exist.", + "Group 'Role456(Loc456)' is invalid. Location with Code 'Loc456' is archived or does not exist." + ] + } +} +``` \ No newline at end of file diff --git a/source/index.html.md b/source/index.html.md index 7494f2fd758..c603f30d92b 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -17,7 +17,6 @@ includes: - user-mgmt-api - user-mgmt/get-api - user-mgmt/post-patch-api - - user-mgmt/group-membership - dev-support search: true From 7b03f9ff1c03639a5913cfef407936dbb267fea1 Mon Sep 17 00:00:00 2001 From: "Nathan.Lawson" Date: Mon, 3 Feb 2025 14:56:28 -0700 Subject: [PATCH 4/8] CR comment fixes --- source/includes/user-mgmt/post-patch-api.md | 148 ++++++++++---------- source/index.html.md | 6 +- 2 files changed, 78 insertions(+), 76 deletions(-) diff --git a/source/includes/user-mgmt/post-patch-api.md b/source/includes/user-mgmt/post-patch-api.md index 50297e6a14d..d8a45ddacfd 100644 --- a/source/includes/user-mgmt/post-patch-api.md +++ b/source/includes/user-mgmt/post-patch-api.md @@ -1,5 +1,7 @@ ## Add or Modify Data +This section outlines the available POST and PATCH endpoints designed for modifying employee and user data. These endpoints support updating existing records and inserting new records. Requests should be formatted in JSON. + > User Management API Endpoint - replace **intelex_object** with the system name of your object ``` @@ -8,16 +10,6 @@ https://intelex_url/api/v2/EmployeeUserAccess ### Add Data -#### POST /EmployeeUserAccess - -##### Body Parameters - -| Parameter | Description | -| ---------- | ---------------------------------------------------------------------------------------------------------------- | -| field_name | The value you want to set for an employee or user field. Replace _field_name_ with the name of the employee or user field | - -See [Request Payload Field Reference](#request-payload-field-reference) for detailed field information. - > Example Request ```javascript @@ -54,9 +46,19 @@ request.AddParameter("application/json", "{\r\n \"EmployeeNumber\": \"001\",\ IRestResponse response = client.Execute(request); ``` -A succesful POST to the EmployeeUserAccess endpoint will respond with a 201 Created response code and a json body containing the Id for the created employee and user records. +#### POST /EmployeeUserAccess -> Example of successful create (POST) response +##### Body Parameters + +| Parameter | Description | +| ---------- | ---------------------------------------------------------------------------------------------------------------- | +| field_name | The value you want to set for an employee or user field. Replace _field_name_ with the name of the employee or user field | + +See [Request Payload Field Reference](#request-payload-field-reference) for detailed field information. + +A successful POST to the EmployeeUserAccess endpoint will respond with a 201 Created response code and a json body containing the Id for the created employee and user records. + +> Example Response ```json { @@ -66,24 +68,6 @@ A succesful POST to the EmployeeUserAccess endpoint will respond with a 20 ### Modify Data -#### PATCH /EmployeeUserAccess({id}) - -##### URL Parameters - -| Parameter | Description | -| ---------------------- | -------------------------------------------------- | -| employee_id _(optional)_ | The Intelex UID of the employee/user being updated | - -NOTE: You may also provide a valid Id or EmployeeNumber in the payload as the identifier used to update the record. - -##### Body Parameters - -| Parameter | Description | -| ---------- | ---------------------------------------------------------------------------------------------------------------- | -| field_name | The value you want to set for and employee or user field. Replace _field_name_ with the name of the employee or user field | - -See [Request Payload Field Reference](#request-payload-field-reference) for detailed field information. - > Example Request ```javascript @@ -116,7 +100,25 @@ request.AddParameter("application/json", "{\r\n \"EmployeeNumber\": \"001\",\ IRestResponse response = client.Execute(request); ``` -A succesful PATCH to the EmployeeUserAccess endpoint will respond with a 204 No Content response code. +#### PATCH /EmployeeUserAccess({id}) + +##### URL Parameters + +| Parameter | Description | +| ---------------------- | -------------------------------------------------- | +| employee_id _(optional)_ | The Intelex UID of the employee/user being updated | + +NOTE: You may also provide a valid Id or EmployeeNumber in the payload as the identifier used to update the record. + +##### Body Parameters + +| Parameter | Description | +| ---------- | ---------------------------------------------------------------------------------------------------------------- | +| field_name | The value you want to set for and employee or user field. Replace _field_name_ with the name of the employee or user field | + +See [Request Payload Field Reference](#request-payload-field-reference) for detailed field information. + +A successful PATCH to the EmployeeUserAccess endpoint will respond with a 204 No Content response code. ### Request Payload Field Reference @@ -136,7 +138,7 @@ Some settings flags may be ignored if the flag is not relevant to the request ty IgnoreUserAccess - Skips user access creation. Employee record will still be created. +
  • Skips user access creation. Employee record will still be created.
    • @@ -171,7 +173,7 @@ Some settings flags may be ignored if the flag is not relevant to the request ty RemoveFromUnlistedGroups -
  • Existing employees only
    • +
  • Existing employees only.
  • Remove employee membership from any previously assigned groups that are not specified in the Groups field.
  • This field is still respected if DoNotAddGroupAssignments is set.
    • @@ -192,7 +194,7 @@ Properties denoted with a \* are required and must be included in t Flag -
  • Indicates whether employe should be archived in the system:
    • +
  • Indicates whether employee should be archived in the system:
    • A = Active employee (default)
    • I = Inactive (archived) employee
      • @@ -203,7 +205,7 @@ Properties denoted with a \* are required and must be included in t EmployeeNumber* - Primary Key; Unique identifier of employee. +
    • Primary Key; Unique identifier of employee.
      • @@ -216,43 +218,43 @@ Properties denoted with a \* are required and must be included in t Prefix - Prefix of employee (e.g., Mr., Mrs., Ms.) +
    • Prefix of employee (e.g., Mr., Mrs., Ms.)
      • FirstName* - First name of employee. +
    • First name of employee.
      • LastName* - Last name of employee. +
    • Last name of employee.
      • MiddleName - Middle name of employee +
    • Middle name of employee.
      • DisplayName - Last name of employee. +
    • Last name of employee.
      • Suffix - Suffix of employee (e.g., Jr., Sr.) +
    • Suffix of employee (e.g., Jr., Sr.)
      • Email - Email address of employee. +
    • Email address of employee.
      • @@ -270,7 +272,7 @@ Properties denoted with a \* are required and must be included in t - Date_Of_Hire + DateOfHire
    • Date of hire of employee.
    • Please speak with your consultant to confirm the date format for your subdomain.
      • @@ -279,19 +281,19 @@ Properties denoted with a \* are required and must be included in t SupervisorNumber - Employee Number of supervisor of employee. +
    • Employee Number of supervisor of employee.
      • PositionTitle - Job title of employee. +
    • Job title of employee.
      • Notes - Open text field found in employee profile. +
    • Open text field found in employee profile.
      • @@ -304,13 +306,13 @@ Properties denoted with a \* are required and must be included in t Company - Company name of employee. +
    • Company name of employee.
      • ContractorName - Contractor company name of employee. +
    • Contractor company name of employee.
      • @@ -330,41 +332,41 @@ Properties denoted with a \* are required and must be included in t ContractorNotes - Open text field found in employee profile. +
    • Open text field found in employee profile.
      • StreetAddress - Street address of employee. +
    • Street address of employee.
      • City - City of employee. +
    • City of employee.
      • State - State of employee. +
    • State of employee.
      • ZipCode - Zip code (or postal code) of employee. +
    • Zip code (or postal code) of employee.
      • Gender - Gender of employee. +
    • Gender of employee.
      • - Date_Of_Birth + DateOfBirth
    • Date of birth of employee.
    • Please speak with your consultant to confirm the date format for your subdomain.
      • @@ -373,19 +375,19 @@ Properties denoted with a \* are required and must be included in t SSN - Social security number of employee. +
    • Social security number of employee.
      • EmergencyContact - Emergency contact information of employee. +
    • Emergency contact information of employee.
      • EmergencyPhone - Emergency phone number of employee. +
    • Emergency phone number of employee.
      • @@ -413,25 +415,25 @@ Properties denoted with a \* are required and must be included in t PhoneNumber - Phone number of employee. +
    • Phone number of employee.
      • HourlyWage - Hourly wage of employee. +
    • Hourly wage of employee.
      • JobCode - Job Code for employee. +
    • Job Code for employee.
      • WorkStatus - [Legal] Work status of employee. +
    • [Legal] Work status of employee.
      • @@ -440,8 +442,8 @@ Properties denoted with a \* are required and must be included in t
    • Semicolon (;) delimited list of elements that this employee is a member of (excluding Everyone group).
    • Each element can be the Caption or GUID of any Group or Location Role.
    • Groups includes Security Groups, Roles, Location Roles and Training Workgroups.
      • -
    • If an element is invalid, then the processing of this particular element is skipped; other elements for the employee are not skipped.
      • -
    • Notation for Location Role: RoleCaption(LocationCodeOrGUID)
      • +
    • If an element is invalid, the request will fail with validation errors in the response.
      • +
    • Notation for Location Role: RoleNameOrGUID(LocationCodeOrGUID)
      • @@ -468,7 +470,7 @@ Payload fields that are associated with the user record to be created or updated IsLocked - Locks or unlocks the user +
    • Locks or unlocks the user
      • @@ -533,30 +535,30 @@ Payload fields that are associated with the user record to be created or updated LongDate - d, dd = day; ddd, dddd = day of week; M, MM = month; yy, yyyy = year +
    • d, dd = day; ddd, dddd = day of week; M, MM = month; yy, yyyy = year
      • LongTime - h, hh = hour (12-hour format); H, HH = hour (24-hour format); m = minutes; s = seconds; tt = A.M. or P.M. +
    • h, hh = hour (12-hour format); H, HH = hour (24-hour format); m = minutes; s = seconds; tt = A.M. or P.M.
      • ShortDate - d, dd = day; ddd, dddd = day of week; M, MM = month; yy, yyyy = year +
    • d, dd = day; ddd, dddd = day of week; M, MM = month; yy, yyyy = year
      • ShortTime - h, hh = hour (12-hour format); H, HH = hour (24-hour format); m = minutes; s = seconds; tt = A.M. or P.M. +
    • h, hh = hour (12-hour format); H, HH = hour (24-hour format); m = minutes; s = seconds; tt = A.M. or P.M.
      • -> Full example request body payload +> Example Request Body ```json { @@ -643,7 +645,7 @@ Example payload validations for modification include:
    • Duplicate primary key identifiers (E.g. EmployeeNumber, DisplayName)
    -> Example response with validation errors +> Example Response With Validation Errors ```json { @@ -693,7 +695,7 @@ Example group validations include:
  • Location code does not exist or is invalid.
    • -> Example of a payload with Groups +> Example Groups Payload ```json { @@ -701,7 +703,7 @@ Example group validations include: } ``` -> Example response with group validation errors +> Example Response With Group Validation Errors ```json { diff --git a/source/index.html.md b/source/index.html.md index c603f30d92b..cedab96fd17 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -9,14 +9,14 @@ includes: - api-reference - object-data-api - task-api + - user-mgmt-api + - user-mgmt/get-api + - user-mgmt/post-patch-api - acts-api - acts/reference - acts/get_api - acts/post_api - acts/delete_api - - user-mgmt-api - - user-mgmt/get-api - - user-mgmt/post-patch-api - dev-support search: true From 00c97ed94b669b68fa52535944f36e467ec46af4 Mon Sep 17 00:00:00 2001 From: Peter deNoyelles <47636921+pdenoyelles@users.noreply.github.com> Date: Tue, 4 Feb 2025 12:35:37 -0700 Subject: [PATCH 5/8] [ILX-50576] Add GET documentation to the User Management API section. (#39) --- source/includes/_object-data-api.md | 1 + source/includes/_user-mgmt-api.md | 10 +++++----- source/includes/user-mgmt/get-api.md | 13 ++++++++++--- source/includes/user-mgmt/post-patch-api.md | 11 +++++++---- source/stylesheets/screen.css.scss | 2 +- 5 files changed, 24 insertions(+), 13 deletions(-) diff --git a/source/includes/_object-data-api.md b/source/includes/_object-data-api.md index a054ff60625..96f23cbc419 100644 --- a/source/includes/_object-data-api.md +++ b/source/includes/_object-data-api.md @@ -59,6 +59,7 @@ Sometimes you might need to access data from system objects that contain data su System Object | Description | System Name --------- | ----------- | --------- Employees | Intelex Employees | SysEmployeeEntity +Users | Intelex Users | SysUserEntity Locations | Intelex locations | SysLocationEntity Groups | Intelex Employee groups | SysGroupEntity EDIS Staging Table | Staging table used to process EDIS | EmployeeStagingEntity diff --git a/source/includes/_user-mgmt-api.md b/source/includes/_user-mgmt-api.md index 13a99aa1c45..f084a08012c 100644 --- a/source/includes/_user-mgmt-api.md +++ b/source/includes/_user-mgmt-api.md @@ -1,5 +1,5 @@ -# USER MANAGEMENT API - -The User Management API provides the ability to externally manage employee and user acccess in Intelex. - -Functionality for this endpoint includes employee and user [creation](#add-data) and [modification](#modify-data) with the ability to archive employees and revoke user access. Requests may also optionally [assign and revoke group membership](#group-membership) to the employee. +# User Management API + +The User Management API provides the ability to externally manage employee and user acccess in Intelex. + +Functionality for this endpoint includes employee and user [creation](#add-data) and [modification](#modify-data) with the ability to archive employees and revoke user access. Requests may also optionally [assign and revoke group membership](#group-membership) to the employee. diff --git a/source/includes/user-mgmt/get-api.md b/source/includes/user-mgmt/get-api.md index 35d424acfd9..a852301d8d6 100644 --- a/source/includes/user-mgmt/get-api.md +++ b/source/includes/user-mgmt/get-api.md @@ -1,3 +1,10 @@ -## Retrieve Data - -This section outlines the blah blah blah +## Retrieve Data + +To retrieve data relevant to Employees and Users that are being managed through the User Management API, please refer to the [Object Data API](#object-data-api) section. + +The applicable User Management [System Objects](#system-objects) that can be accessed will be `SysEmployeeEntity` and `SysUserEntity`. + +Please note: There are some SysUserEntity fields that can be set/updated but are marked as sensitive so they will not be returned when retrieving SysUserEntities. **This is not an exhaustive list and columns marked as sensitive could change in the future**: + +* `SecondaryPassword` +* `DateSecondaryPasswordModified` \ No newline at end of file diff --git a/source/includes/user-mgmt/post-patch-api.md b/source/includes/user-mgmt/post-patch-api.md index d8a45ddacfd..197ca364f68 100644 --- a/source/includes/user-mgmt/post-patch-api.md +++ b/source/includes/user-mgmt/post-patch-api.md @@ -151,16 +151,18 @@ Some settings flags may be ignored if the flag is not relevant to the request ty RevokeUserAccess -
  • Existing users only. Only respected if user access is requested.
    • +
  • Existing users only.
  • Revokes access for the specified user.
    • -
  • +
  • Revokes API access for the specified user (if applicable).
    • ArchiveIfTasksAssigned -
  • Existing users only. Only respected if user access is requested.
    • -
  • +
  • Existing users only.
    • +
  • Only respected if Flag = I in Employee Fields.
    • +
  • Allows Employees who have tasks assigned to them to be archived.
    • +
  • If ArchiveIfTasksAssigned is not set and the specified employee has tasks assigned, the request will fail with an error and the associated user will be locked.
    • @@ -200,6 +202,7 @@ Properties denoted with a \* are required and must be included in t
  • I = Inactive (archived) employee
  • Archiving an an employee will also remove the associated user's access, if available.
    • +
  • Only existing employees can be archived. You cannot create a new "Inactive" employee.
    • diff --git a/source/stylesheets/screen.css.scss b/source/stylesheets/screen.css.scss index 362974cb4df..a6d8c2aba73 100644 --- a/source/stylesheets/screen.css.scss +++ b/source/stylesheets/screen.css.scss @@ -41,7 +41,7 @@ html, body { // Section headers - .tocify-item[data-unique="api-reference"], .tocify-item[data-unique="object-data-api"], .tocify-item[data-unique="task-api"], .tocify-item[data-unique="developer-support"], .tocify-item[data-unique="interface-api"], .tocify-item[data-unique="package-api"] { + .tocify-item[data-unique="api-reference"], .tocify-item[data-unique="object-data-api"], .tocify-item[data-unique="task-api"], .tocify-item[data-unique="developer-support"], .tocify-item[data-unique="interface-api"], .tocify-item[data-unique="package-api"], .tocify-item[data-unique="user-management-api"] { text-transform: uppercase; margin-top: 1em; margin-bottom: 0.5em; From aaa93871a8a06263f15784bcbd4075077b26b214 Mon Sep 17 00:00:00 2001 From: "Nathan.Lawson" Date: Tue, 4 Feb 2025 12:37:46 -0700 Subject: [PATCH 6/8] Minor fixes to example payload --- source/includes/user-mgmt/post-patch-api.md | 24 ++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/source/includes/user-mgmt/post-patch-api.md b/source/includes/user-mgmt/post-patch-api.md index 197ca364f68..ed2091677ff 100644 --- a/source/includes/user-mgmt/post-patch-api.md +++ b/source/includes/user-mgmt/post-patch-api.md @@ -2,7 +2,7 @@ This section outlines the available POST and PATCH endpoints designed for modifying employee and user data. These endpoints support updating existing records and inserting new records. Requests should be formatted in JSON. -> User Management API Endpoint - replace **intelex_object** with the system name of your object +> User Management API Endpoint ``` https://intelex_url/api/v2/EmployeeUserAccess @@ -580,22 +580,22 @@ Payload fields that are associated with the user record to be created or updated "Email": "john.doe@intelex.com", "IsSupervisor": "Y", "EmployeeType": "Hourly", - "Date_Of_Hire": "2019-11-25", + "DateOfHire": "2019-11-25", "SupervisorNumber": "001", "PositionTitle": "Line Worker", "Notes": "Notes for me", "Contractor": "Y", "Company": "Intelex", - "ContractorName": "Sears", + "ContractorName": "Contractor Name", "ContractExpiry": "2026-12-30", "InsuranceExpiry": "2026-12-31", "ContractorNotes": "Notes for the Contractor", - "StreetAddress": "5613 DTC Pkwy Suite 320", - "City": "Greenwood Village", - "State": "Colorado", - "ZipCode": "80111", + "StreetAddress": "70 University Ave #800", + "City": "Toronto", + "State": "Ontario", + "ZipCode": "M5J 2M4", "Gender": "M", - "Date_Of_Birth": "1999-06-23", + "DateOfBirth": "1999-06-23", "SSN": "111-11-1111", "EmergencyContact": "Jane Doe", "EmergencyPhone": "123-456-7890", @@ -614,10 +614,10 @@ Payload fields that are associated with the user record to be created or updated "TimeZone": "Eastern Standard Time", "LicenseType": "Full Access", "CultureName": "English (United States)", - "LongDate": "", - "LongTime": "", - "ShortDate": "", - "ShortTime": "", + "LongDate": "dddd, MMMM dd, yyyy", + "LongTime": "h:mm:ss tt", + "ShortDate": "M/d/yyyy", + "ShortTime": "h:mm tt", "Groups": "Claims Administrator(01E4C606-2F03-4044-B6B1-079AE288D82A);7F50AC4D-93F4-4DF9-90AF-00D7DF663720" } From f8b57ced5f1314943a6009d440ba4deb64c20a2e Mon Sep 17 00:00:00 2001 From: Peter deNoyelles Date: Wed, 5 Feb 2025 12:27:13 -0700 Subject: [PATCH 7/8] Add required version to top section description --- source/includes/_user-mgmt-api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/includes/_user-mgmt-api.md b/source/includes/_user-mgmt-api.md index f084a08012c..901faaa7b07 100644 --- a/source/includes/_user-mgmt-api.md +++ b/source/includes/_user-mgmt-api.md @@ -3,3 +3,5 @@ The User Management API provides the ability to externally manage employee and user acccess in Intelex. Functionality for this endpoint includes employee and user [creation](#add-data) and [modification](#modify-data) with the ability to archive employees and revoke user access. Requests may also optionally [assign and revoke group membership](#group-membership) to the employee. + +Requires Platform Version 6.6.16 or higher \ No newline at end of file From 8af0dd7de3fa3fa8f02cbbb82436171833c96fec Mon Sep 17 00:00:00 2001 From: "Nathan.Lawson" Date: Fri, 7 Feb 2025 11:26:27 -0700 Subject: [PATCH 8/8] Update DisplayName field requirements based on updated validation --- source/includes/user-mgmt/post-patch-api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/includes/user-mgmt/post-patch-api.md b/source/includes/user-mgmt/post-patch-api.md index ed2091677ff..a30ee156ef1 100644 --- a/source/includes/user-mgmt/post-patch-api.md +++ b/source/includes/user-mgmt/post-patch-api.md @@ -245,7 +245,10 @@ Properties denoted with a \* are required and must be included in t DisplayName -
  • Last name of employee.
    • +
  • Display name of employee.
    • +
  • If present, cannot be blank ("") or empty (" ").
    • +
  • If not present or null in create payload, defaults to FirstName + LastName.
    • +
  • If not present or null in update payload, value will not be updated.