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

We need to have the SOAPUI installed to test the REST API functionality. There are many other tools that 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

NOTE: To access the SCIM REST resources, your job role must have the ASE_REST_SERVICE_ACCESS_IDENTITY_INTEGRATION_PRIV privilege. This privilege is already granted to the IT Security Manager [ORA_FND_IT_SECURITY_MANAGER_JOB] job role.

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.

Input the URI and click OK.

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>

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.

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":"[email protected]",
"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.

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

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'

Now the URI would be:

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

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.

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 protected]"

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

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

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

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

API End point:

https://POD.oraclecloud.com/hcmRestApi/scim/Bulk

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

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 need 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"
}
}
]
}

Note: Even though the method that we use is PATCH, we need to use the POST method to submit the payload else you would get an error. Also, make sure the payload is in a similar format as above. Else you might get 403 or 400 errors. If you are using postman to test, it might not work, try using the soap UI tool.

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 Code	Description
200 OK	The request was successfully completed. A 200 status code is returned for a successful GET or POST method.
201 Created	The 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 Accepted	The 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 Content	The server has fulfilled the request but doesn’t return a response body.
400 Bad Request: validation failures, schema violations	The 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 Unauthorized	The request isn’t authorized. The authentication credentials included with this request are missing or invalid.
403 Forbidden	The 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 Acceptable	The 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 Conflict	The 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 Failed	A 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 Large	The bulk request exceeds the allowed maximum number of operations.
415 Unsupported Media Type	The 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 Error	The server encountered an unexpected condition that prevented it from fulfilling the request.
501 Method not allowed	The server doesn’t support the requested method.

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":"[email protected]",
       "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":"[email protected]",
       "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:

• Fusion Security: Using SCIM REST API (Doc ID 2346455.1)
• REST APIs for Common features in Oracle Applications Cloud for 20A
• REST APIs for Oracle HCM Cloud 20A

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.