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 new file mode 100644 index 00000000000..901faaa7b07 --- /dev/null +++ b/source/includes/_user-mgmt-api.md @@ -0,0 +1,7 @@ +# 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. + +Requires Platform Version 6.6.16 or higher \ No newline at end of file diff --git a/source/includes/user-mgmt/get-api.md b/source/includes/user-mgmt/get-api.md new file mode 100644 index 00000000000..a852301d8d6 --- /dev/null +++ b/source/includes/user-mgmt/get-api.md @@ -0,0 +1,10 @@ +## 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 new file mode 100644 index 00000000000..a30ee156ef1 --- /dev/null +++ b/source/includes/user-mgmt/post-patch-api.md @@ -0,0 +1,724 @@ +## 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 + +``` +https://intelex_url/api/v2/EmployeeUserAccess +``` + +### Add Data + +> 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); +}); +``` + +```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); +``` + +#### 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. + +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 +{ + "Id": "43d1b046-156a-4715-bf96-10f71690a528" +} +``` + +### Modify Data + +> 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); +``` + +#### 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 + +#### Settings Flags + +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 an 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.
    • +
  • Revokes access for the specified user.
    • +
  • Revokes API access for the specified user (if applicable).
    • +
    ArchiveIfTasksAssigned +
  • 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.
    • +
    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 + +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 employee 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.
    • +
  • Only existing employees can be archived. You cannot create a new "Inactive" employee.
    • +
    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 +
  • 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.
    • +
    Suffix +
  • Suffix of employee (e.g., Jr., Sr.)
    • +
    Email +
  • Email address of employee.
    • +
    IsSupervisor +
  • Indicates whether employee has direct reports or not.
    • +
  • Valid values are Y or N
    • +
    EmployeeType +
  • Type of Employee.
    • +
  • Must be the Name of a valid SysEmployeeType record.
    • +
    DateOfHire +
  • 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.
    • +
  • Valid values are Y or N
    • +
    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.
    • +
    DateOfBirth +
  • 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, the request will fail with validation errors in the response.
    • +
  • Notation for Location Role: RoleNameOrGUID(LocationCodeOrGUID)
    • +
    + +#### User Fields + +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.
    • +
  • Example: (UTC-05:00) Eastern Time (US & Canada)
    • +
    LicenseType* +
  • Identifies specific V6 license type assigned in License Type field in user profile.
    • +
  • Valid values are:
    • +
      +
    • Concurrent Access
      • +
    • Full Access
      • +
    • System Administrator
      • +
    +
    CultureName +
  • For clients who have purchased additional languages.
    • +
  • Identifies culture assigned in Culture field in user profile.
    • +
  • "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 + +```json +{ + "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", + "DateOfHire": "2019-11-25", + "SupervisorNumber": "001", + "PositionTitle": "Line Worker", + "Notes": "Notes for me", + "Contractor": "Y", + "Company": "Intelex", + "ContractorName": "Contractor Name", + "ContractExpiry": "2026-12-30", + "InsuranceExpiry": "2026-12-31", + "ContractorNotes": "Notes for the Contractor", + "StreetAddress": "70 University Ave #800", + "City": "Toronto", + "State": "Ontario", + "ZipCode": "M5J 2M4", + "Gender": "M", + "DateOfBirth": "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": "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" +} +``` + +### 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: + + + +#### Update (PATCH) Payload Validation + +Example payload validations for modification include: + + + +> 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." + ] + } +} +``` + +### 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: + + +"Groups" include Security Groups, Roles, Location Roles and Training Workgroups, or any object that inherits from the Group Entity. + +#### Roles and Location Roles + +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: + + +> Example Groups Payload + +```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 4f18320125f..cedab96fd17 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -4,11 +4,14 @@ title: Intelex API Reference language_tabs: - javascript: JavaScript - csharp: C# - + 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 @@ -16,7 +19,5 @@ includes: - acts/delete_api - dev-support - search: true --- - 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;