REST APIs to load, get, update and reset password for users
REST APIs to load, get, update and reset password for users

 1,544 total views

In this article we will look into how to use rest services to perform GET/POST/DELETE/PATCH operations on the User Business object.

You can follow these steps and use the REST APIs for any business object, as the basic steps would be the same except the Payload and the Method that needs to passed on to make the request.

Without much delay, we will get started with the steps:

We need to have the SOAPUI installed to test the REST API functionality. There are many other tools which can be used, however SOAP UI is a powerful and most widely used tool, hence going with it.

If you want to know more details on how to use SOAP services then refer this post which provides details on it.

First we need to get the REST API endpoint for User Business object to proceed further.

Please refer to Oracle Documentation for 20A release to get the list of REST service endpoints for all business objects. With every release Oracle is introducing REST support for new business objects. So we will have to check the latest release documentation to check if the required business object has the REST APIs enabled.

Here we can find the REST API Endpoint for User as /hcmRestApi/scim/Users

Now we need to attach it to the POD link to get the complete URI for it. The URL for REST API is called as URI (Uniform Resource Identifiers)

R13 URI : https://{POD Name}.fa.{DataCenter}.oraclecloud.com/hcmRestApi/scim/Users

https://abcd-test.fa.us6.oraclecloud.com/hcmRestApi/scim/Users

Now that we have the URI ready, let’s go to SOAP UI and create a new REST Project with this URI.

Creating a New REST Project
Creating a New REST Project
Input the URI and Click OK for REST project
Providing the Input URI of REST API

Input the URI and click OK.

Initial REST project screen
Initial REST project screen

We can see the Resource populated for the Users hcmRestApi/scim/Users

Now click on the “Auth” at the left bottom and select the Basic type and click OK>

Basic Authentication type
Enter the Authentication Details
Enter the Authentication Details

Input the Username, Password (please ensure that this user must be assigned the ‘IT Security Manager [ORA_FND_IT_SECURITY_MANAGER_JOB]‘ role) and change the Pre-emptive auth to “Authenticate pre-emptively” and finally click “Auth” again to minimize the Authentication window.

Methods supported by Rest APIs
Methods supported by Rest APIs

Now we will look into the Methods supported by REST API.

GET – GET requests are the most common and widely used methods in APIs and websites. Simply put, the GET method is used to retrieve data from a server at the specified resource. We can use filters to get the required data.

POST – POST requests are used to send data to the API server to create or update a resource

DELETE – DELETE method is exactly as it sounds: delete the resource at the specified URL

PATCH PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request- URI

PUT, HEAD, OPTIONS, TRACE – These methods are are rarely used. You can explore more on these methods.

Now we will try to create a User using the POST method. REST APIs use the Payload in JSON (JavaScript Object Notation) format which is lightweight data-interchange format and it is easy for Humans to read and write, easy for Machines to parse and generate.

Sample Payload for User Creation:

{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"name":{
"familyName":"User",
"givenName":"Test"
},
"active":true,
"userName":"TEST_USER",
"emails":[
{
"primary":true,
"value":"Test@test.com",
"type":"W"
}
],
"displayName":"Test User",
"externalId":"externalId12345:"
}

Now, we will try to change the Method to POST and add the above payload and run it to check the response.

POST method has been successful and the user got created successfully
POST method has been successful and the user got created successfully

Now we will go to Security Console > Users tab and verify if the user has been created or not.

User got created successfully
User got created successfully

We can see that the User got created successfully.

Sample Payload for GET Method for single user:

The URI for GET method for a single user is /hcmRestApi/scim/Users/{id}

https://abcd-test.fa.us6.oraclecloud.com/hcmRestApi/scim/Users/{id}

Here the {id} is the GUID of the User and can be retrieved from PER_USERS table

select USER_GUID from per_users where username = 'TEST_USER'
Retrieve GUID of User using SQL query to be used in API
Retrieve GUID of User using SQL Query to be used in API

Now the URI would be:

https://abcd-test.fa.us6.oraclecloud.com/hcmRestApi/scim/Users/A4A6DF5C332F86B9E0503B0AFC8455F8
GET is successful and we got the details of the loaded user
GET is successful and we got the details of the loaded user

Sample Payload for GET Method for multiple users using filter:

The URI for GET method for multiple user is /hcmRestApi/scim/Users. However we have to apply filters on top of this URI to get the required data.

Filters that can be applied to GET method
Filters that can be applied to GET method

We can either add the filters to the URI or we can add in SOAPUI manually.

https://abcd-test.fa.us6.oraclecloud.com/hcmRestApi/resources/latest/emps?q=PersonId=<PersonId>&fields=UserName&onlyData=true
https://abcd-test.fa.us6.oraclecloud.com/hcmRestApi/scim/Users?filter=userName EQ "email@domain.com"

Sample Payload for DELETE method for User:

The URI for DELETE method for a single user is /hcmRestApi/scim/Users/{id}

https://abcd-test.fa.us6.oraclecloud.com/hcmRestApi/scim/Users/{id}

Here the {id} is the GUID of the User and can be retrieved from PER_USERS table

select USER_GUID from per_users where username = 'TEST_USER'

Now the URI for TEST_USER would be:

https://abcd-test.fa.us6.oraclecloud.com/hcmRestApi/scim/Users/A4A6DF5C332F86B9E0503B0AFC8455F8
Delete has been successful
DELETE Method has been successful

After the DELETE method is successful it doesn’t show any message but the user will get deleted from the application.

We are unable to find the user now post DELETE method
We are unable to find the user now post DELETE method

Sample Payload for PATCH Method for User Password Reset in Bulk:

The URI for PATCH Method is /hcmRestApi/scim/Users and we use it mainly to reset the password in bulk whenever there is a requirement.

URI - https://abcd-test.fa.us6.oraclecloud.com/hcmRestApi/scim/Users

Payload:

{
"Operations":[
{
"method":"PATCH",
"path":"/Users/USER1_GUID",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"password": "Welc0me12"
}
},
{
"method":"PATCH",
"path":"/Users/USER2_GUID",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"password": "Welc0me12"
}
}
]
}

We have to provide the GUID for the users in this payload. USER1_GUID and USER2_GUID needs to be replaced with the actual GUID values. Also the default password or the user specific password can also be provided in the payload..

{
"Operations":[
{
"method":"PATCH",
"path":"/Users/8B68EBB77E1BC1D3E0503B0AC2D34E59",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"password": "Welc0me12"
}
},
{
"method":"PATCH",
"path":"/Users/8B68EBB77E1CC1D3E0503B0AC2D34E59",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"password": "Welc0me12"
}
}
]
}

Status codes List and explanation:

When you call any REST resource, the Response header returns one of the standard HTTP status codes. The following table lists the supported status codes:

HTTP Status CodeDescription
200 OKThe request was successfully completed. A 200 status code is returned for a successful GET or POST method.
201 CreatedThe request has been fulfilled and resulted in a new resource being created. The response includes a Location header containing the canonical URI for the newly created resource. A 201 status code is returned from a synchronous resource creation or an asynchronous resource creation that completed before the response was returned.
202 AcceptedThe request has been accepted for processing, but the processing hasn’t been completed. The request may or may not eventually be acted upon because it may be disallowed at the time processing takes place. When specifying an asynchronous (__detached=true) resource creation (for example, when deploying an application), or update (for example, when redeploying an application), a 202 status code is returned if the operation is still in progress. If __detached=false, a 202 status code may be returned if the underlying operation doesn’t complete in a reasonable amount of time. The response contains a Location header of a job resource that the client should poll to determine when the job has finished. Also, returns an entity that contains the current state of the job.
204 No ContentThe server has fulfilled the request but doesn’t return a response body.
400 Bad Request: validation failures, schema violationsThe request could not be processed because it contains missing or invalid information (such as, a validation error on an input field, a missing required value, and so on).
401 UnauthorizedThe request isn’t authorized. The authentication credentials included with this request are missing or invalid.
403 ForbiddenThe server doesn’t support the requested operation on the specified resource.
404 Not found <Additional information about the object not found>The request includes a resource URI that doesn’t exist.
406 Not AcceptableThe resource identified by this request can’t generate a representation corresponding to one of the media types in the Accept header of the request. For example, the client’s Accept header request XML be returned, but the resource can return only JSON.
409 ConflictThe specified version number doesn’t match with the latest version number of the resource, or a service provider didn’t create a new or a duplicate resource.
412 Precondition FailedA precondition in the request header failed. For example, the request failed to update as the resource id on the server changed since the last retrieval.
413 Request Entity Too LargeThe bulk request exceeds the allowed maximum number of operations.
415 Unsupported Media TypeThe request could not be processed because it contains formats that are not supported by the resource.
422 Unprocessable Entity <Additional information about the error>The syntax of the request parameters is incorrect.
424 Failed Dependency <Additional information on failed dependency>The request could not be processed because the requested action depended on another action that failed.
500 Internal Server ErrorThe server encountered an unexpected condition that prevented it from fulfilling the request.
501 Method not allowedThe server doesn’t support the requested method.
Status Codes and explanation

Sample Payload for Bulk Activate users:

{
"Operations":[
{
"method":"PATCH",
"path":"/Users/ENTER_USER1_GUID_HERE",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"active":true
}
},
{
"method":"PATCH",
"path":"/Users/ENTER_USER2_GUID_HERE",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"active":true
}
}
]
}

Sample Payload for Bulk Inactivate users:

{
"Operations":[
{
"method":"PATCH",
"path":"/Users/ENTER_USER1_GUID_HERE",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"active":false
}
},
{
"method":"PATCH",
"path":"/Users/ENTER_USER2_GUID_HERE",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"active":false
}
}
]
}

Sample Payload for Bulk Delete users:

{
"Operations":[
{
"method":"DELETE",
"path":"/Users/ENTER_USER1_GUID_HERE",
"bulkId":"clientBulkId1"
},
{
"method":"DELETE",
"path":"/Users/ENTER_USER2_GUID_HERE",
"bulkId":"clientBulkId1"
}
]
}

Sample Payload for Bulk Update Usernames:

{
"Operations":[
{
"method":"PATCH",
"path":"/Users/ENTER_USER1_GUID_HERE",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"userName":"ENTER_USERNAME_HERE"
}
},
{
"method":"PATCH",
"path":"/Users/ENTER_USER2_GUID_HERE",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"userName":"ENTER_USERNAME_HERE"
}
}
]
}

Sample Payload for Bulk Add/Revoke Roles for Users:

{
"Operations":[
{
"method":"PATCH",
"path":"/Roles/ENTER_ROLE_GUID_HERE",
"bulkId":"clientBulkId1",
"data": {
"members": [
{
"value": "ENTER_USER_GUID_HERE",
"operation": "REMOVE"
}]
}
},
{
"method":"PATCH",
"path":"/Roles/ENTER_ROLE_GUID_HERE",
"bulkId":"clientBulkId1",
"data": {
"members": [
{
"value": "ENTER_USER_GUID_HERE",
"operation": "ADD"
}]
}
}
]
}

Sample Payload for Bulk Update email addresses for Users:

{
"Operations":[
{
"method":"PATCH",
"path":"/Users/ENTER_USER1_GUID_HERE",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"emails":[
  {
   "value":"ENTER_EMAIL_HERE"
  }
 ]
}
},
{
"method":"PATCH",
"path":"/Users/ENTER_USER2_GUID_HERE",
"bulkId":"clientBulkId1",
"data":{
"schemas":[
"urn:scim:schemas:core:2.0:User"
],
"emails":[
  {
   "value":"ENTER_EMAIL_HERE"
  }
 ]
}
}
]
}

Sample Payload for Bulk Create Users:

NOTE: The bulkId attribute value should be set to UNIQUE value, while creating user accounts in BULK using POST Method. You may use a common value for the bulkId attribute while using PATCH, DELETE, PUT methods in a Bulk operation.

{
"Operations":[
{
   "method":"POST",
   "path":"/Users",
   "bulkId":"clientBulkId1",
   "data":{
     "schemas":[
      "urn:scim:schemas:core:2.0:User",
      "urn:scim:schemas:extension:fa:2.0:faUser"
     ],
     "name":{
      "familyName":"Jones",
      "givenName":"Kerry"
     },
     "active":true,
     "userName":"JONESK_OPERATIONS",
     "emails":[
      {
       "primary":true,
       "value":"J.K@oracle.com",
       "type":"W"
      }
     ],
     "displayName":"Kerry Jones",
     "urn:scim:schemas:extension:fa:2.0:faUser": {
        "userCategory": "EMPLOYEE"
   }
  },
{
   "method":"POST",
   "path":"/Users",
   "bulkId":"clientBulkId2",
   "data":{
     "schemas":[
      "urn:scim:schemas:core:2.0:User",
       "urn:scim:schemas:extension:fa:2.0:faUser"
     ],
     "name":{
      "familyName":"Smith",
      "givenName":"David"
     },
     "active":true,
     "userName":"SMITHD_SALES",
     "emails":[
      {
       "primary":true,
       "value":"D.S@oracle.com",
       "type":"W"
      }
     ],
     "displayName":"David Smith",
     "urn:scim:schemas:extension:fa:2.0:faUser": {
        "userCategory": "SUPPLIER"
   }
   }
  }
]
}

These other payloads can be tried in a similar way like the first three POST/GET and DELETE methods. We need to change the Method and add the payload and submit.

If you want to perform some operations or invoke REST services in batch, then you either need to do some python/shell scripting to achieve your requirement or have a middleware like OIC/Mulesoft/Dell Boomi to handle the tasks.

References:

If you have any questions, please feel free to reach out to me by posting in comments section.

If you are interested in learning all Fusion Technical tools go through this post

If you liked the article, please share it with your friends/ colleagues/ teammates or anyone who might also benefit from it.

The following two tabs change content below.
Sricharan is a Fusion HCM Solution Architect with over 13+ years of overall experience and 5+ years of Fusion experience. He is passionate about technical aspects of Fusion HCM and writes interesting articles on HCM Extracts, HCM Data Loader, Fast Formula, BI Publisher, Integrations and Automation etc.

This Post Has 9 Comments

  1. viswa

    Nice Article Sricharan.

  2. Sricharan

    Thanks for the compliment.
    Keep reading and subscribe if you haven’t done yet.

  3. Gopi

    Excellent info Bro, very well covered all the topics with detailed information. Thanks

    1. Sricharan

      Thank you for your compliment Gopi.
      Keep subscribing for latest updates.

  4. Mohan

    I didn’t see any thing related bulk users to reset the password.

    1. Sricharan

      “Sample Payload for PATCH Method for User Password Reset” is the section that you need to use for bulk reset of passwords. You need to prepare payload in JSON format and then run it to get the passwords reset for users.

  5. Jyothi

    WoW…Thanks Srisaran for the great articles..

  6. Pavan

    Good article and very use full… I will try this and let you If I have any concerns

  7. Pavan

    Hi Sricharan,

    Is there any way to reset all users passwords at a time?

    Thanks,
    Pavan.

Leave a Reply