Configure access for a person
Creating employees and managers who are able to perform basic tasks involves much more than simply calling the Create Persons operation. While this topic cannot cover every configuration step necessary to build out the ecosystem necessary for employees and managers to function, we will look at the simplest steps that need to be taken in a configured environment to enable your employees and managers to see timecards, add punches, view schedules, and request and approve time off.
Licenses
A license is a seat given by a manager or administrator to a specific person to allow that person to gain access to features and services. People may be assigned licenses to one or more packages. Licenses are the primary means by which access to features and services of the products in a package is enforced.
You can assign licenses only for packages to which your business or institution has subscribed as long as there are seats remaining.
To add a license to an existing person using the API, follow the procedure below.
Request
Call Update Person by ID (PUT /v1/commons/persons/{id}) with the new license included in the request body. This will not overwrite existing licenses--it adds the new license or licenses specified to the existing list, much like a PATCH operation.
For this example, we call PUT /v1/commons/persons/5 with the following request body:
{
"personIdentity": {
"personKey": 5
},
"personInformation": {
"personLicenseTypes": [
{
"activeFlag": true,
"licenseTypeName": "Work"
}
]
}
}
Response
A success response returns HTTP status code 200 and a response body similar to the following example.
{
"personIdentity": {
"personKey": 5
},
"personInformation": {
"personLicenseTypes": [
{
"activeFlag": true,
"licenseTypeName": "Work"
}
]
}
}
Note that only the submitted change is displayed in the response.
Verify
To verify all licenses in this example, call the Retrieve Person by ID (GET /v1/commons/persons/{id}) operation using an ID of 5: GET /v1/commons/persons/5.
The response body contains the full list of licenses. Below is a truncated response from our example. Note the presence of Work license.
{
"personIdentity": {
"personKey": 5
},
...
"personInformation": {
...
"personLicenseTypes": [
{
"activeFlag": true,
"licenseTypeName": "Employee"
},
{
"activeFlag": true,
"licenseTypeName": "Manager"
},
{
"activeFlag": true,
"licenseTypeName": "Absence"
},
{
"activeFlag": true,
"licenseTypeName": "Workforce MobileManager"
},
{
"activeFlag": true,
"licenseTypeName": "Optimized Scheduling with Forecasting"
},
{
"activeFlag": true,
"licenseTypeName": "Workforce MobileEmployee"
},
{
"activeFlag": true,
"licenseTypeName": "Workforce TabletManager"
},
{
"activeFlag": true,
"licenseTypeName": "Work"
},
{
"activeFlag": true,
"licenseTypeName": "Workforce TabletEmployee"
},
{
"activeFlag": true,
"licenseTypeName": "Salaried Timekeeping"
}
]
}
}
Access Profiles
Function Access Profiles
Function Access Profiles (FAPs) contain permissions to points in the hierarchy of functions, known as access control points (ACPs). The access control points can correspond to general functions, such as Timecard and Schedule, or to individual options, such as birth dates or wage rates.
In the Create and Update Persons operations, Function Access Profiles are assigned using accessProfileName within accessAssignment, which is part of personInformation.
A great deal of what a person can see and do is controlled by the assigned FAP. Configure FAPs for logical groupings of employee and manager types appropriate for your organization.
You can create new FAPs, update existing FAPs, and more by using the operations available in Common Resources > Function Access Profiles. You can view all of the FAPs currently available in your system by calling the Retrieve All Function Access Profiles or by Name (GET /v1/commons/function_access_profiles) operation.
The example employee Roger is assigned the Retail Employee FAP.
Request
Call Retrieve All Function Access Profiles or by Name with the name=Retail Employee query parameter:
GET /v1/commons/function_access_profiles?name=Retail Employee
Response
[
{
"id": 63,
"name": "Retail Employee",
"description": "Manufacturing Employee FAP",
"isDefault": false,
"permissionTypes": [
{
"controlPointKey": "SE_COSTCENTER_TRANSFERS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_COSTCENTER_TRANSFERS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "SHOW_PERSON_NUM",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "XML",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EMAIL_IF_EDITED",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EMAIL_WHEN_APPROVED",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EMAIL_WHEN_SIGNEDOFF",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WAGES",
"scopeName": "ONLY_SELF",
"actionName": "VIEW"
},
{
"controlPointKey": "EA_ALLOW_NEGATIVES",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_TCE_COMMENTS",
"scopeName": "ALL",
"actionName": "ADD"
},
{
"controlPointKey": "EA_TCE_COMMENTS",
"scopeName": "ALL",
"actionName": "DELETE"
},
{
"controlPointKey": "EA_DURATION_AND_SHIFT",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_ADD_APPROVAL",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_REMOVE_APPROVAL",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_ACCOUNT_TRANSFERS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_PAYCODE_EDITS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_PUNCH_EDITS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_VIEW_PAYCODE_AMOUNTS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_VIEW_SCHEDULER",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_VIEW_TRANSFERS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_WORKRULE_TRANSFERS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_TOTALIZE",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_TOTALS_BREAKDOWN",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_TOTALIZE_ON_FLY",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_DISPLAY_DAY_BEFORE_AND_AFTER",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_EMAIL_TIMECARD",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "TS_CANCEL_MEAL_DEDUCTS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_PAYCODE_EDITS_FROM_SCHEDULE",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_JOB_TRANSFERS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_TOTALS_BY_JOB",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "MY_EARNINGS_HISTORY",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WBAP_MYACTIONLIST",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WBAP_START_PROCESS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WBAP_FORMS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "CONTROL_CENTER_ACCESS",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WBAP_TASKLIST",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EA_TCE_ADD_OR_REMOVE_NOTE",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "MY_REQUEST_AP",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "CALENDAR_EMP_VIEW",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "FALCON",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "MAPPING_CATEGORY",
"scopeName": "ALL",
"actionName": "VIEW"
},
{
"controlPointKey": "METRIC_DEFINITION",
"scopeName": "ALL",
"actionName": "VIEW"
},
{
"controlPointKey": "KPI_DEFINITION",
"scopeName": "ALL",
"actionName": "VIEW"
},
{
"controlPointKey": "EMP_PROFILE_PHOTO_UPLOAD",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "CONFIGURATION_APP",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "EMPLOYMENT_TERM_VIEW_OF_SCHEDULE",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WFF_RUN_VOLUME_FORECAST",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WFF_RUN_LABOR_FORECAST",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WFF_RESTORE_VOLUME_FORECAST",
"scopeName": "NONE",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WFF_FORECAST_PLANNER_CONFIGURATION",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "WFF_FORECAST_PROFILE",
"scopeName": "ALL",
"actionName": "ALLOWED"
},
{
"controlPointKey": "REST_API_SETUP",
"scopeName": "ALL",
"actionName": "ALLOWED"
}
]
}
]
Notes of interest
| Control Point Key | Friendly name | Comment |
|---|---|---|
| SHOW_PERSON_NUM | Show Person Number | Employees can see the ID number assigned to them in People Information. |
| *_TRANSFERS | Perform account transfers | Enables employees to change primary accounts, depending on where they work for a particular time. |
| EA_ADD_APPROVAL | Add approval | Employees can approve their timecards. |
| EA_REMOVE_APPROVAL | Remove approval | Employees can remove approval from their timecards. |
| EA_VIEW_PAYCODE_AMOUNTS | Pay Codes in My Timecard > View | Employees can see pay codes in their timecards. |
| EA_TOTALIZE | Calculate totals in My Timecard | Employees can see totals in the timecard. |
| EA_TOTALIZE_ON_FLY | Calculate totals on-the-fly in My Timecard | Employees can see totals immediately after making a change in their timecard. |
| EA_VIEW_TRANSFERS | Transfers > View transfers | Employees can view transfers made in their timecards. |
Display profiles
Use Display Profiles to configure and assign display preferences. Display Profiles can be based on a job, department, or geographical location.
In the Create and Update Persons operations, Display Profiles are assigned using preferenceProfileName within accessAssignment, which is part of personInformation.
You can create new Display Profiles, update existing Display Profiles, and more by using the operations available in Common Resources > Display Profiles. You can view at all of the Display Profiles currently available in your system by calling the Retrieve All Display Profiles (GET /v1/commons/display_profiles) operation.
The example employee Roger is assigned the Retail Employee DP Display Profile.
Request
Call Retrieve Display Profiles (POST /v1/commons/display_profiles/multi_read) with the following request payload:
[
{
"qualifier": "Retail Employee DP"
}
]
Response
[
{
"id": 58,
"name": "Retail Employee DP",
"description": "Display Profile for Retail Hourly Employees",
"dataViewProfile": {
"id": 3,
"qualifier": "Std_DataView_Profile"
},
"defaultProfile": false,
"homePage": {
"id": 4,
"qualifier": "Hourly Employee Home Page Profile"
},
"displayShiftLabels": false,
"displayDurationInHours": true,
"displayDayDurationInHours": true,
"hyperfindProfile": {
"id": -1,
"qualifier": "All Hyperfinds"
},
"controlCenterProfile": {
"id": 1,
"qualifier": "Employee CC Profile"
},
"schedulePlannerProfile": {
"id": 5,
"qualifier": "Schedule Planner Profile"
},
"essCalendarProfile": {
"id": 8,
"qualifier": "Employee Calendar Profile"
},
"schedulePeriod": {
"id": 1,
"qualifier": "Weekly"
}
}
]
Notes of interest
| Element | Comment |
|---|---|
homePage | Controls what Home Page tiles appear. Configure and use an appropriate Home Page Profile to ensure each group has ready access to their most important functions. For example, include the My Time Off tile to allow employees to request time off. |
dataViewProfile | Controls what Dataviews are available. |
controlCenterProfile | Controls what messages appear in the Control Center. For example, an employee might have System Messages, Tasks, and Attendance and Leave messages, whereas as manager profile might add Employee Requests as well. |
Other Profiles
| Profile | Friendly name | Comment |
|---|---|---|
notificationProfileName | Notification Profile | Indicates the destination for generic notifications, based on the notification's priority level. See Administration > Application Setup > System Configuration > Notification Profiles. |
delegateProfileName | Delegate Profile — (Managers) | Names the individuals who can act in the manager’s role when the manager is absent; for example, to approve timecards, absences, and so on. |
gdapAssignments > gdapName | Generic Data Access Profiles — (Managers) | Divides configured pay rules and accruals data among different business units or locations within your organization. |
Process Profiles
Assign a Process profile to an employee or manager. The Process profile enables the use of Actions or My Actions (for example, time-off requests), based on the process templates that are in the profile.
The example employee Roger is assigned the EmpProcessProfile Process Profile.
Request
Call Retrieve Process Profile by Person Number with the person_number query parameter:
GET /v1/commons/persons/process_profiles?person_number=123456
Response
{
"employeeProcessProfileName": "EmpProcessProfile",
"managerProcessProfileName": "Empty Profile",
"personIdentity": {
"personNumber": "123456"
}
}
Notes of interest
| Element | Comment |
|---|---|
employeeProcessProfileName | The assigned Employee Process Profile. |
managerProcessProfileName | The assigned Manager Process Profile. |
Activity profiles
Activity profiles are part of the Activities (Work) domain. The Activities (Work) domain allows you to use activities to monitor and react to progress on production, grant, or project work by tracking your employees, capital assets, and materials. Activities provides real-time information to improve decision-making about how to best use your workforce and resources.
Activity profiles help to limit the amount of data that employees can select, such as forms and result codes.
- For activity profiles assigned to individual people, all settings in the profile are applicable.
- Variances are applied to the adjusted start and stop times of employee activity events only.
- Activity profiles can be assigned to employees or managers.
Refer to A Guide to Activities (Work) for more information about the Activities (Work) domain.
Prerequisities
The person making the call and the person or persons receiving the Activity profile assignment must have the Activity (Work) license. Refer to the Licenses section for more information on assigning licenses using the API.
Example request
Call PUT /v1/commons/persons/100 with the following request payload.
{
"personIdentity": {
"personKey": 100
},
"personInformation": {
"workEmployee": {
"profileName": "Example Profile 1",
"defaultActivityName": "Example Errand",
"idleActivityName": "Idle Activity 1",
"unpaidActivityName": "Unpaid Meal Break 1",
"paidActivityName": "Paid Meal Break 1"
}
}
}
Example response
A success response returns HTTP status code 200 and a response body similar to the following example.
{
"personIdentity": {
"personKey": 100
},
"personInformation": {
"workEmployee": {
"defaultActivityName": "Example Errand",
"idleActivityName": "Idle Activity 1",
"paidActivityName": "Paid Meal Break 1",
"profileName": "Example Profile 1",
"unpaidActivityName": "Unpaid Meal Break 1"
}
}
}
Note that the remainder of the person record is unchanged--this API operation updates only the portion of the record submitted in the request, much like a PATCH operation.
Next steps
In addition to the assignments that can be made using the Create or Update Person API operations, many other entities can be assigned to a person record using the API. Continue to the Guide to Person Assignments or the Guide to Aggregated Person Assignments for more information. You can also refer to these API resources within the Person Assignments domain, where you can find request and response models and object and property descriptions.
Updated over 1 year ago