Manage User Accounts
You may need to manage user accounts for the workers in your organization to provide access to certain applications or task flows that workers are required to use in their work assignments. You can use the userAccounts
API to perform actions such as view, create, update, link, unlink, and so on. You can also perform custom actions such as password reset and update.
Let's discuss these scenarios:
- View all the user accounts
- Create a user account
- View a user account
- Unlink a user account
- Link a user account
- Update the user name of an account
- Update the password of an account
- Trigger a password reset for an account
- Suspend a user account
- Unsuspend a user account
View All User Accounts
Let's say that Jason is an administrator who manages user accounts for the workers in his organization. He wants to retrieve all the user accounts and view the account details.
To view all the user accounts:
- Perform a GET operation on the
userAccounts
resource. - Verify the account details returned in the response.
Example URL
Use this resource URL format.
GET
/hcmRestApi/resources/11.13.18.05/userAccounts
Example Response
Here's an example of the response body in JSON format.
{
"items": [
{
"UserId": 60,
"Username": "CUST_CONTRACT_MGR_OPERATIONS",
"SuspendedFlag": false,
"PersonId": 100010024201426,
"PersonNumber": "WRKR-10024201426",
"CredentialsEmailSentFlag": true,
"GUID": "5A25572D96277A00C0547E3A715EF682",
"CreatedBy": "0",
"CreationDate": "2009-05-25T00:00:00+00:00",
"LastUpdatedBy": "TM-MFITZIMMONS",
"LastUpdateDate": "2019-09-10T18:10:15.321+00:00",
"links": [
{
...}
]
},
{
"UserId": 300100003417358,
"Username": "DATA_STEWARD_MANAGER_VISION_CORPORATION",
"SuspendedFlag": false,
"PersonId": null,
"PersonNumber": null,
"CredentialsEmailSentFlag": true,
"GUID": "C79DBCC8F107FDE2CD3B938BEF5A94CE",
"CreatedBy": "HCM_USER10",
"CreationDate": "2011-12-02T04:30:33.660+00:00",
"LastUpdatedBy": "FUSION",
"LastUpdateDate": "2013-08-14T00:48:18+00:00",
"links": [
{
...}
]
},
{
"UserId": 100100081660000,
"Username": "john.doe@example.com",
"SuspendedFlag": false,
"PersonId": 300100069778195,
"PersonNumber": "WRKR-955160008183775",
"CredentialsEmailSentFlag": true,
"GUID": "8091FA12603D206DE050F50AE3921F70",
"CreatedBy": "useraccountsuper",
"CreationDate": "2019-02-14T21:01:35.180+00:00",
"LastUpdatedBy": "useraccountsuper",
"LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
"links": [
{
...}
]
]
}
Create a User Account
Let's say that Jason needs to create a new user account for Andy who recently joined the organization.
To create a new user account:
- Make sure that Manage Enterprise HCM Information task in Oracle HCM Cloud allows user account creation.
- Query the worker by using a query parameter such as person number and retrieve the person ID.
- Set the
Content-Type
toapplication/vnd.oracle.adf.resourceitem+json
. - Perform a POST operation on the
userAccounts
resource by providing the user name and person ID in the request body. - Verify the details of the new user account returned in the response.
Example URL
Use this resource URL format.
POST
/hcmRestApi/resources/11.13.18.05/userAccounts
Example Request
Here's an example of the request body in JSON format.
{
"PersonId": "300100069778195",
"Username": "john.doe@example.com",
"CredentialsEmailSentFlag": "true"
}
Example Response
Here's an example of the response body in JSON format.
{
"UserId": 100100081660000,
"Username": "john.doe@example.com",
"SuspendedFlag": false,
"PersonId": "300100069778195",
"PersonNumber": "WRKR-955160008183775",
"CredentialsEmailSentFlag": true,
"GUID": "8091FA12603D206DE050F50AE3921F70",
"CreatedBy": "useraccountsuper",
"CreationDate": "2019-02-14T21:01:35.180+00:00",
"LastUpdatedBy": "useraccountsuper",
"LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
"links": : [
{...
}
]
}
View a User Account
Jason wants to view the user account that he created for Andy and verify that the details are correct.
To retrieve a user account:
- Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
- Perform a GET operation on the
userAccounts
resource by using the GUID. - Verify the user account details returned in the response.
Example URL
Use this resource URL format.
GET
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70
Example Response
Here's an example of the response body in JSON format.
{
"UserId": 100100081660000,
"Username": "john.doe@example.com",
"SuspendedFlag": false,
"PersonId": 300100069778195,
"PersonNumber": "WRKR-955160008183775",
"CredentialsEmailSentFlag": true,
"GUID": "8091FA12603D206DE050F50AE3921F70",
"CreatedBy": "useraccountsuper",
"CreationDate": "2019-02-14T21:01:35.180+00:00",
"LastUpdatedBy": "useraccountsuper",
"LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
"links": : [
{...
}
]
}
Unlink a User Account
Jason realized that Scott has been assigned an incorrect user account by mistake. He wants to unlink the account.
To unlink a user account:
- Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
- Set the
Content-Type
toapplication/vnd.oracle.adf.resourceitem+json
. - Perform a PATCH operation on the
userAccounts
resource by using the GUID and providing a null value forPersonID
in the request body. - Verify the user account details returned in the response.
Example URL
Use this resource URL format.
PATCH
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70
Example Request
Here's an example of the request body in JSON format.
{
"PersonId": null
}
Example Response
Here's an example of the response body in JSON format.
{
"UserId": 100100081660000,
"Username": "john.doe@example.com",
"SuspendedFlag": false,
"PersonId": null,
"PersonNumber": null,
"CredentialsEmailSentFlag": true,
"GUID": "8091FA12603D206DE050F50AE3921F70",
"CreatedBy": "useraccountsuper",
"CreationDate": "2019-02-14T21:01:35.180+00:00",
"LastUpdatedBy": "useraccountsuper",
"LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
"links": : [
{...
}
]
}
Link a User Account
Let's say that Jason wants to link Andy's person record to a new user account, which isn't linked to any person record yet.
To link a user account:
- Query the worker by using a query parameter such as person number and obtain the person ID.
- Query the user account to be assigned by using a query parameter such as person name and obtain the GUID of the user account.
- Set the
Content-Type
toapplication/vnd.oracle.adf.resourceitem+json
. - Perform a PATCH operation on the
userAccounts
resource by using the GUID and providing the obtained person ID value forPersonID
in the request body. - Verify the user account details returned in the response.
Example URL
Use this resource URL format.
PATCH
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70
Example Request
Here's an example of the request body in JSON format.
{
"PersonId": 300100069778195
}
Example Response
Here's an example of the response body in JSON format.
{
"UserId": 100100081660000,
"Username": "johndoe@example.com",
"SuspendedFlag": false,
"PersonId": 300100069778195,
"PersonNumber": "WRKR-955160008183775",
"CredentialsEmailSentFlag": true,
"GUID": "8091FA12603D206DE050F50AE3921F70",
"CreatedBy": "useraccountsuper",
"CreationDate": "2019-02-14T21:01:35.180+00:00",
"LastUpdatedBy": "useraccountsuper",
"LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
"links": : [
{...
}
]
}
Update a User Name
Jason noticed that the user name of an existing user account is incorrect and wants to update it.
To update a user name:
- Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
- Set the
Content-Type
toapplication/vnd.oracle.adf.resourceitem+json
. - Perform a PATCH operation on the
userAccounts
resource by using the GUID and providing the new value forUsername
in the request body. - Verify the user account details returned in the response.
Example URL
Use this resource URL format.
PATCH
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70
Example Request
Here's an example of the request body in JSON format.
{
"Username": "jane.doe@example.com"
}
Example Response
Here's an example of the response body in JSON format.
{
"UserId": 100100081660000,
"Username": "jane.doe@example.com",
"SuspendedFlag": false,
"PersonId": 300100069778195,
"PersonNumber": "WRKR-955160008183775",
"CredentialsEmailSentFlag": true,
"GUID": "8091FA12603D206DE050F50AE3921F70",
"CreatedBy": "useraccountsuper",
"CreationDate": "2019-02-14T21:01:35.180+00:00",
"LastUpdatedBy": "useraccountsuper",
"LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
"links": : [
{...
}
]
}
Update a Password
Let's say that Jason wants to update the password of an existing user account to a specific value for a test user.
To update a password:
- Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
- Set the
Content-Type
toapplication/vnd.oracle.adf.action+json
. - Perform a POST operation on the
userAccounts
resource by using the GUID and the custom actionupdatePassword
, and providing the new password in the request body. - Verify the result in the response.
Example URL
Use this resource URL format.
POST
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70/action/updatePassword
Example Request
Here's an example of the request body in JSON format.
{
"pwd": "NewPassw0rd"
}
Example Response
Here's an example of the response body in JSON format.
{
"result": "Success"
}
Trigger a Password Reset
Let's say that Jason wants to trigger a password reset flow for a user account to reset the password.
To trigger a password reset:
- Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
- Set the
Content-Type
toapplication/vnd.oracle.adf.action+json
. - Perform a POST operation on the
userAccounts
resource by using the GUID and the custom actionresetPassword
. - Verify the result in the response.
Example URL
Use this resource URL format.
POST
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70/action/resetPassword
Example Response
Here's an example of the response body in JSON format.
{
"result": "Success"
}
Suspend a User Account
Let's say that Jason wants to limit Andy's access to the application and suspend his user account temporarily.
To suspend a user account:
- Query the user account by using a query parameter such as person number and get the GUID of the user account.
- Set the
Content-Type
toapplication/vnd.oracle.adf.resourceitem+json
. - Perform a PATCH operation on the
userAccounts
resource by using the GUID and providing the valuetrue
for theSuspendedFlag
attribute in the request body. - Verify the user account details returned in the response.
Example URL
Use this resource URL format.
PATCH
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70
Example Request
Here's an example of the request body in JSON format.
{
"SuspendedFlag": true
}
Example Response
Here's an example of the response body in JSON format.
{
"UserId": 100100081660000,
"Username": "jane.doe@example.com",
"SuspendedFlag": true,
"PersonId": 300100069778195,
"PersonNumber": "WRKR-955160008183775",
"CredentialsEmailSentFlag": true,
"GUID": "8091FA12603D206DE050F50AE3921F70",
"CreatedBy": "useraccountsuper",
"CreationDate": "2019-02-14T21:01:35.180+00:00",
"LastUpdatedBy": "useraccountsuper",
"LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
"links": : [
{...
}
]
}
Unsuspend a User Account
Jason now wants to allow access to Andy, whose user account is currently suspended.
To unsuspend a user account:
- Query the user account by using a query parameter such as person number and obtain GUID of the the user account.
- Set the
Content-Type
toapplication/vnd.oracle.adf.resourceitem+json
. - Perform a PATCH operation on the
userAccounts
resource by using the GUID and providing the valuefalse
for theSuspendedFlag
attribute in the request body. - Verify the user account details returned in the response.
Example URL
Use this resource URL format.
PATCH
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70
Example Request
Here's an example of the request body in JSON format.
{
"SuspendedFlag": false
}
Example Response
Here's an example of the response body in JSON format.
{
"UserId": 100100081660000,
"Username": "jane.doe@example.com",
"SuspendedFlag": false,
"PersonId": 300100069778195,
"PersonNumber": "WRKR-955160008183775",
"CredentialsEmailSentFlag": true,
"GUID": "8091FA12603D206DE050F50AE3921F70",
"CreatedBy": "useraccountsuper",
"CreationDate": "2019-02-14T21:01:35.180+00:00",
"LastUpdatedBy": "useraccountsuper",
"LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
"links": : [
{...
}
]
}
Delete a User Account
Let's say that Jason created an incorrect user account and wants to delete it.
To delete a user account:
- Query the user account by, using a query parameter such as person number and obtain the user account GUID.
- Set the
Content-Type
toapplication/vnd.oracle.adf.resourceitem+json
. - Perform a DELETE operation on the
userAccounts
resource by using the GUID. - Verify the status in the response.
Example URL
Use this resource URL format.
DELETE
/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70
Example Response
Here's an example of the response body in JSON format.
Status: 204 - No content