Create multiple person records
This topic explains how to construct requests for creating one or more persons with either the employee or manager role using the Create Persons operation.
Example requests are POSTed to the Create Persons URL:
https://<<hostName>>/api/v1/commons/persons/multi_create
This operation allows you to create new people entries in the system and to pass information that corresponds to the options in the Maintenance > People Information > Employee section of the user interface.
By following this example, you will be able to create:
- employees who can:
- Log in to the UI
- Access their timecard
- Access their schedule
- Request time off
- managers who can:
- Log in to the UI
- Access all of the same functions as employees
- View and edit employee timecards
- View and edit employee schedules
- Approve a time off request
Example request
In this example, the request:
- creates a new, active employee named "Roger Wilco"
- defines Roger's user name, password, authentication type, and work email address
- assigns Roger a job, a manager, a base wage, basic licenses, a display profile, and a labor account
- creates a new, active manager named "Earl Grey"
- defines Earl's user name, password, authentication type, and work email address
- assigns Earl a job, a base wage, basic licenses, a display profile, and a labor account
[
{
"personInformation": {
"accessAssignment": {
"accessProfileName": "Retail Manager",
"managerPayCodeName": "Retail Pay Codes",
"managerViewPayCodeName": "Retail Pay Codes",
"managerWorkRuleName": "Retail Work Rules",
"notificationProfileName": "All",
"preferenceProfileName": "Retail DP",
"professionalPayCodeName": "Retail Pay Codes",
"professionalWorkRuleName": "Retail Work Rules",
"shiftCodeName": "Retail Templates"
},
"emailAddresses": [
{
"address": "[email protected]",
"contactTypeName": "Work",
"hasEmailNotificationDelivery": true
}
],
"employmentStatusList": [
{
"effectiveDate": "2019-08-13",
"employmentStatusName": "Active",
"expirationDate": "3000-01-01"
}
],
"person": {
"birthDate": "1986-02-04",
"firstName": "Earl",
"lastName": "Grey",
"fullName": "Grey, Earl",
"hireDate": "2016-08-13",
"personNumber": "2001",
"shortName": "EGrey"
},
"personAuthenticationTypes": [
{
"activeFlag": true,
"authenticationTypeName": "Basic"
}
],
"personLicenseTypes": [
{
"activeFlag": true,
"licenseTypeName": "Employee"
},
{
"activeFlag": true,
"licenseTypeName": "Manager"
},
{
"activeFlag": true,
"licenseTypeName": "Absence"
},
{
"activeFlag": true,
"licenseTypeName": "Workforce MobileManager"
},
{
"activeFlag": true,
"licenseTypeName": "Workforce TabletManager"
},
{
"activeFlag": true,
"licenseTypeName": "Hourly Timekeeping"
},
{
"activeFlag": true,
"licenseTypeName": "Scheduling"
}
],
"userAccountStatusList": [
{
"effectiveDate": "2016-08-13",
"expirationDate": "3000-01-01",
"userAccountStatusName": "Active"
}
]
},
"jobAssignment": {
"baseWageRates": [
{
"effectiveDate": "1753-01-01",
"expirationDate": "3000-01-01",
"hourlyRate": 42.15
}
],
"jobAssignmentDetails": {
"payRuleName": "USNY-RT-FT",
"timeZoneName": "(GMT -05:00) Eastern Time"
},
"primaryLaborAccounts": [
{
"effectiveDate": "2019-08-13",
"expirationDate": "3000-01-01",
"organizationPath": "Organization/United States/Metropolitan Store/California/Example Mart/Admin/Store Manager"
}
]
},
"user": {
"userAccount": {
"userName": "EarlGrey",
"userPassword": "3x@mplE1"
}
},
"gdapAssignments": [
{
"defaultSwitch": true,
"effectiveDate": "2019-08-15",
"expirationDate": "3000-01-01",
"role": "MANAGER_ROLE",
"gdapName": "Retail Manager GDAP"
}
]
},
{
"personInformation": {
"accessAssignment": {
"accessProfileName": "Retail Employee",
"notificationProfileName": "All",
"preferenceProfileName": "Retail Employee DP",
"professionalPayCodeName": "Retail Pay Codes",
"professionalWorkRuleName": "Retail Work Rules",
"shiftCodeName": "Retail Templates"
},
"emailAddresses": [
{
"address": "[email protected]",
"contactTypeName": "Work",
"hasEmailNotificationDelivery": true
}
],
"employmentStatusList": [
{
"effectiveDate": "2019-08-15",
"employmentStatusName": "Active",
"expirationDate": "3000-01-01"
}
],
"person": {
"birthDate": "1986-02-04",
"firstName": "Roger",
"lastName": "Wilco",
"fullName": "Wilco, Roger",
"hireDate": "2019-08-15",
"personNumber": "1234567",
"shortName": "RWilco"
},
"personAuthenticationTypes": [
{
"activeFlag": true,
"authenticationTypeName": "Basic"
}
],
"personLicenseTypes": [
{
"activeFlag": true,
"licenseTypeName": "Employee"
},
{
"activeFlag": true,
"licenseTypeName": "Absence"
},
{
"activeFlag": true,
"licenseTypeName": "Hourly Timekeeping"
},
{
"activeFlag": true,
"licenseTypeName": "Scheduling"
}
],
"userAccountStatusList": [
{
"effectiveDate": "2019-08-15",
"expirationDate": "3000-01-01",
"userAccountStatusName": "Active"
}
]
},
"jobAssignment": {
"baseWageRates": [
{
"effectiveDate": "2019-01-01",
"expirationDate": "3000-01-01",
"hourlyRate": 20.15
}
],
"jobAssignmentDetails": {
"payRuleName": "USNY-RT-FT",
"supervisorName": "Grey, Earl",
"supervisorPersonNumber": "2001",
"timeZoneName": "(GMT -05:00) Eastern Time"
},
"primaryLaborAccounts": [
{
"effectiveDate": "2019-08-15",
"expirationDate": "3000-01-01",
"organizationPath": "Organization/United States/Metropolitan Store/New York/Example Mart/Retail/Cashier"
}
]
},
"user": {
"userAccount": {
"logonProfileName": "Professional Hourly Employee",
"userName": "RogerWilco",
"userPassword": "3x@mpl3"
}
}
}
]
Notes of interest
- Since the JSON is processed sequentially, if you are passing people who report to other people being created in the same request, you must specify the supervisors (in order of hierarchy, from highest to lowest) before you specify employees who report to those supervisors.
- The organization path of each person record's primary labor account must be a job in your organization's business structure.
- For date properties, the values for the earliest possible date (also known as the "beginning of time") and the latest possible date (also known as the "end of time") are 1900-01-01 and 3000-01-01, respectively.
- Refer to the Resource Details of the Create Persons POST
/v1/commons/persons/multi_createoperation for descriptions of each object, array, and property. - The structure for each record passed in this request exactly matches the individual structure passed in a Create Person GET
/v1/commons/personsrequest.
Example response
The response is an array containing the created person records, each of which now contains the personIdentity array which has one property: a system-generated ID, known as a person key or employee ID. The response otherwise mimics the successful request body.
[
{
"personIdentity": {
"personKey": 50800
},
"personInformation": {
"accessAssignment": {
"accessProfileName": "Retail Manager",
"managerPayCodeName": "Retail Pay Codes",
"managerViewPayCodeName": "Retail Pay Codes",
"managerWorkRuleName": "Retail Work Rules",
"notificationProfileName": "All",
"preferenceProfileName": "Retail DP",
"professionalPayCodeName": "Retail Pay Codes",
"professionalWorkRuleName": "Retail Work Rules",
"shiftCodeName": "Retail Templates"
},
"emailAddresses": [
{
"address": "[email protected]",
"contactTypeName": "Work",
"hasEmailNotificationDelivery": true
}
],
"employmentStatusList": [
{
"effectiveDate": "2019-08-13",
"employmentStatusName": "Active",
"expirationDate": "3000-01-01"
}
],
"person": {
"birthDate": "1986-02-04",
"firstName": "Earl",
"lastName": "Grey",
"fullName": "Grey, Earl",
"hireDate": "2016-08-13",
"personNumber": "2001",
"shortName": "EGrey"
},
"personAuthenticationTypes": [
{
"activeFlag": true,
"authenticationTypeName": "Basic"
}
],
"personLicenseTypes": [
{
"activeFlag": true,
"licenseTypeName": "Employee"
},
{
"activeFlag": true,
"licenseTypeName": "Manager"
},
{
"activeFlag": true,
"licenseTypeName": "Absence"
},
{
"activeFlag": true,
"licenseTypeName": "Workforce MobileManager"
},
{
"activeFlag": true,
"licenseTypeName": "Workforce TabletManager"
},
{
"activeFlag": true,
"licenseTypeName": "Hourly Timekeeping"
},
{
"activeFlag": true,
"licenseTypeName": "Scheduling"
}
],
"userAccountStatusList": [
{
"effectiveDate": "2016-08-13",
"expirationDate": "3000-01-01",
"userAccountStatusName": "Active"
}
]
},
"jobAssignment": {
"baseWageRates": [
{
"effectiveDate": "1753-01-01",
"expirationDate": "3000-01-01",
"hourlyRate": 42.15
}
],
"jobAssignmentDetails": {
"payRuleName": "USNY-RT-FT",
"timeZoneName": "(GMT -05:00) Eastern Time"
},
"primaryLaborAccounts": [
{
"effectiveDate": "2019-08-13",
"expirationDate": "3000-01-01",
"organizationPath": "Organization/United States/Metropolitan Store/California/Example Mart/Admin/Store Manager"
}
]
},
"user": {
"userAccount": {
"userName": "EarlGrey",
"userPassword": "3x@mplE1"
}
},
"gdapAssignments": [
{
"defaultSwitch": true,
"effectiveDate": "2019-08-15",
"expirationDate": "3000-01-01",
"role": "MANAGER_ROLE",
"gdapName": "Retail Manager GDAP"
}
]
},
{
"personIdentity": {
"personKey": 50801
},
"personInformation": {
"accessAssignment": {
"accessProfileName": "Retail Employee",
"notificationProfileName": "All",
"preferenceProfileName": "Retail Employee DP",
"professionalPayCodeName": "Retail Pay Codes",
"professionalWorkRuleName": "Retail Work Rules",
"shiftCodeName": "Retail Templates"
},
"emailAddresses": [
{
"address": "[email protected]",
"contactTypeName": "Work",
"hasEmailNotificationDelivery": true
}
],
"employmentStatusList": [
{
"effectiveDate": "2019-08-15",
"employmentStatusName": "Active",
"expirationDate": "3000-01-01"
}
],
"person": {
"birthDate": "1986-02-04",
"firstName": "Roger",
"lastName": "Wilco",
"fullName": "Wilco, Roger",
"hireDate": "2019-08-15",
"personNumber": "123456",
"shortName": "RWilco"
},
"personAuthenticationTypes": [
{
"activeFlag": true,
"authenticationTypeName": "Basic"
}
],
"personLicenseTypes": [
{
"activeFlag": true,
"licenseTypeName": "Employee"
},
{
"activeFlag": true,
"licenseTypeName": "Absence"
},
{
"activeFlag": true,
"licenseTypeName": "Hourly Timekeeping"
},
{
"activeFlag": true,
"licenseTypeName": "Scheduling"
}
],
"userAccountStatusList": [
{
"effectiveDate": "2019-08-15",
"expirationDate": "3000-01-01",
"userAccountStatusName": "Active"
}
]
},
"jobAssignment": {
"baseWageRates": [
{
"effectiveDate": "2019-01-01",
"expirationDate": "3000-01-01",
"hourlyRate": 20.15
}
],
"jobAssignmentDetails": {
"payRuleName": "USNY-RT-FT",
"supervisorName": "Grey, Earl",
"supervisorPersonNumber": "2001",
"timeZoneName": "(GMT -05:00) Eastern Time"
},
"primaryLaborAccounts": [
{
"effectiveDate": "2019-08-15",
"expirationDate": "3000-01-01",
"organizationPath": "Organization/United States/Metropolitan Store/New York/Example Mart/Retail/Cashier"
}
]
},
"user": {
"userAccount": {
"logonProfileName": "Professional Hourly Employee",
"userName": "RogerWilco",
"userPassword": "3x@mpl3"
}
}
}
]
Next steps
To learn about configuring additional parameters for a person, proceed to the Configure access topic.
Updated over 1 year ago