1. REST API for Oracle CX Sales and B2B ServiceREST API for Sales and Fusion Service in Oracle Fusion Cloud Customer Experience
  2. Use Cases
  3. Manage Sales Resource Life Cycle

Manage Sales Resource Life Cycle

John Smith is a Sales Manager with Vision Corporation. He has several sales people in his organization who are internal resources - persons who are either employee or contingent workers. Vision Corporation uses Oracle CX Sales and Fusion Service with a third-party human resources management system (HRMS), First Software. How would you go about integrating the two systems to seamlessly manage the various stages of John's team life cycle, such as hiring, promotion, demotion, transfer, and role change?

Resources as employees are created in First Software and you must synchronize Oracle CX Sales and Fusion Service periodically with the First Software. REST APIs is the best way to bring in information from First Software into Oracle CX Sales and Fusion Service. They let you easily update information in Oracle CX Sales and Fusion Service, as compared to import. You can use the Resources Users API to update information in Sales and Fusion Service. However, you cannot use the API to perform HCM related transactions.

Note:

When creating the user records with phone number you must provide the correct country code.
In this example, you can use the Resource Users REST API to manage the various stages of John's team life cycle as follows:

Note:

Currently, these API methods support only internal resources. Internal resources are employees, or contingent workers who belong to the organization.

If you are using Oracle CX Sales and Fusion Service along with other Oracle Applications Cloud modules, then use this API to manage only internal resources and not to manage workflows related to a HR person or worker. The Human Capital Management Cloud includes REST APIs that support auditing and business workflows.

You cannot use the Resource Users REST API when you have other modules of Oracle Applications Cloud that require:
  • Support for additional attributes (other than those supported by the Resource User REST API).
  • Audit when the HR attributes of a resource change. The REST API only supports management of a person's attributes, it does not support updating or auditing.

You must run the following ESS jobs after creating or updating a resource:

  • Reporting Hierarchy Generation: This job updates the reporting hierarchy in accordance with the changes in internal resource or partner organization hierarchy. The resource's reporting manager is updated unless you run this ESS job.

  • Update Person Search Keywords: This job copies the keyword values automatically from the originating records to the PER_KEYWORDS table, where they are indexed to improve search performance.

  • Send Pending LDAP Requests: This job processes the pending LDAP requests to provision or deprovision the user accounts and roles. You can specify the parameters User Type and Batch Size with this job. You must specify User Type (usually select All); if you leave it as blank, then this process won't process any requests. If you don't set Batch Size, the default will be A for automatic, which is 1/10th of the total requests number. You can specify a number for batch size to instruct the process to group that number of requests together for single batch process. If you want the process to pick up the FAULTED requests from previous run, you can set Batch Size as AF.

Create an Internal Resource

Suppose Jane Doe, a new Sales Representative, joins John Smith's organization (JSmithOrg). To create her as an internal resource:
  1. Construct the request URL for the Create a resource user operation.
  2. Construct the request body with Jane's details. You must provide a unique user name and email for Jane.
  3. Use an appropriate REST API client or the cURL command-line utility to make the POST call.

Note:

When creating an internal resource, you cannot use an existing email or username. If you enter an existing user name or resource, then the following error is displayed in the response.

Please provide a unique combination such that a single resource is identified.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers

cURL Command

curl --user sales_cloud_user -X POST -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers

Request Payload

Here's an example of the request body in JSON format.

{
    "FirstName":"Jane",
    "LastName":"Doe",
    "ResourceEmail":"jane.doe@dnd.vision.com",
    "HireDate":"2018-08-20",
    "LegalEntity":"Vision Corporation",
    "BusinessUnit":"Vision Corporation Enterprise",
    "HRManagerEmailAddress" : "hrmanger@dnd.vision.com",
    "Username" : "jdoe",
    "ResourceOrgRoleCode":"SALES_REPRESENTATIVE",
    "ResourceParentOrganizationName" : "NA Sales",
    "ResourceOrganizationName" : "JSmithOrg",
    "RawWorkPhoneNumber" : "6504461212",
    "AddressLine1" : "100 Oracle Parkway",
    "City" : "Redwood City",
    "State" : "CA",
    "PostalCode" : "944065",
    "Country" : "US",
}

Response Payload

Here's an example of the response body in JSON format.

{
 "PartyName": "Jane Doe",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "100 Oracle Parkway,REDWOOD CITY, CA 944065",
 "Username": "jdoe",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "Jane",
 "LastName": "Doe",
 "ResourcePartyNumber": "Conta765976",
 "State": "CA",
 "ResourceEmail": "jane.doe@dnd.vision.com",
 "RawWorkPhoneNumber": "6505061212",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "100 Oracle Parkway",
 "ResourceOrganizationName": "JSmithOrg",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_REPRESENTATIVE",
 "ResourceParentOrganizationName" : "NA Sales",
 "ResourceManagerFirstName": "John",
 "ResourceManagerLastName": "Smith",
 "HRManagerEmailAddress": "hrmanger@dnd.vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": null,
...
}

Note:

To change user password, see REST API for Oracle HCM Cloud guide.

Create an Internal Resource without a User Account

Katty Smith is a new internal resource in John's organization. However, her manager does not want to create a user account for her. You can create a record for Katty Smith by setting the CreateUserAccountFlag flag to N in the request payload. All the other steps are same as the procedure to Create an Internal Resource.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers

cURL Command

curl --user sales_cloud_user -X POST -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers

Request Payload

Here's an example of the request body in JSON format.

{
    "FirstName":"Katty",
    "LastName":"Smith",
    "ResourceEmail":"katty.smith@dnd.vision.com",
    "HireDate":"2018-08-20",
    "LegalEntity":"Vision Corporation",
    "BusinessUnit":"Vision Corporation Enterprise",
    "HRManagerEmailAddress" : "HR.Manager@dnd.vision.com",
    "ResourceOrgRoleCode":"SALES_MANAGER",
    "ResourceParentOrganizationName" : "HRManager_Org",
    "ResourceOrganizationName" : "kSmithOrg",
    "RawWorkPhoneNumber" : "6504461212",
    "AddressLine1" : "100 Oracle Parkway",
    "City" : "Redwood City",
    "State" : "CA",
    "PostalCode" : "944065",
    "Country" : "US",
    "ResourceStartDate" : "2018-12-05",
    "CreateUserAccountFlag" : "N"
}

Response Payload

Here's an example of the response body in JSON format.

{
 "PartyName": "Katty Smith",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "100 Oracle Parkway,REDWOOD CITY, CA 944065",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "Katty",
 "LastName": "Smith",
 "ResourcePartyNumber": "Conta855676",
 "State": "CA",
 "ResourceEmail": "katty.smith@dnd.vision.com",
 "RawWorkPhoneNumber": "6504461212",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "100 Oracle Parkway",
 "ResourceOrganizationName": "KSmithOrg",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_MANAGER",
 "ResourceParentOrganizationName" : "HRManager_Org",
 "ResourceManagerFirstName": "Phil",
 "ResourceManagerLastName": "Gioco",
 "HRManagerEmailAddress": "HR.Manager@dnd.vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": "N",
...
}

Convert an Existing Employee to a Resource

You can use the Resource Users REST API to convert an existing employee to a resource. Until you identify employees as resources, you can't assign tasks to them. In this scenario, Harry is an existing employee with the APAC organization and you want to convert Harry to a resource. Before converting Harry to a resource, make sure that Harry is an existing employee (see Create a resource user).

You can convert Harry as a resource by submitting a PATCH request on the REST resource using cURL as follows:

cURL Command

curl --user sales_cloud_user -X PATCH -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/resourceUsers/CDRM_914847

Request Body

{     
      
      "ResourceParentOrganizationName" : "APAC",
      "ResourceOrgRoleCode" : "SALES_REPRESENTATIVE"
 
}

Note:

The ResourceOrganizationName attribute is ignored for non-managerial resource.

Response Body

{
    "ResourceProfileId": 300100213482812,
    "PartyName": "Harry Joel",
    "LastUpdateDate": "2020-12-30T07:23:44.036+00:00",
    "LastUpdatedBy": "SALES_ADMIN",
    "CreationDate": "2020-12-30T07:22:37.001+00:00",
    "CreatedBy": "SALES_ADMIN",
    "ResourceType": "INDIVIDUAL",
    "FormattedAddress": null,
    "TimezoneCode": null,
    "Username": "Harry.joel@oracle.com",
    "City": null,
    "Country": null,
    "PostalCode": null,
    "UpdateFlag": "true",
    "DeleteFlag": "false",
    "ResourceOrgRoleCode": "SALES_REPRESENTATIVE",
    "ResourceOrgRoleName": null,
    "FirstName": "Harry",
    "LastName": "Joel",
    "MiddleName": null,
    "Title": "MR.",
    "ResourcePartyNumber": "CDRM_914847",
    "State": null,
    "ResourceEmail": "Harry.joel@oracle.com",
    "WorkPhoneCountryCode": null,
    "RawWorkPhoneNumber": null,
    "MobilePhoneCountryCode": null,
    "RawMobilePhoneNumber": null,
    "FaxCountryCode": null,
    "RawFaxNumber": null,
    "AddressLine1": null,
    "AddressLine2": null,
    "ResourceStartDate": "2007-05-01",
    "ResourceEndDate": "4712-12-31",
    "ResourcePartyId": 300100213482813,
    "ResourceOrganizationName": null,
    "ResourceOrganizationUsage": null,
    "ResourceOrgMemRoleEndDate": null,
    "ResourceParentOrganizationName": "APAC",
    "ResourceOrgManagerEmail": null,
    "ResourceManagerName": null,
    "ResourceManagerFirstName": null,
    "ResourceManagerLastName": null,
    "HRManagerEmailAddress": null,
    "HireDate": "2007-05-01",
    "ResourceOrgMemRoleStartDate": null,
    "IndividualRoleCode": null,
    "IndividualRoleStartDate": null,
    "IndividualRoleEndDate": null,
    "ResourceManagerPartyNumber": null,
    "County": null,
    "Province": null,
    "ResourceManagerPartyId": null,
    "TopResourceFlag": null,
    "PersonNumber": "955160008192779",
    "BusinessUnit": "Vision Corporation Enterprise",
    "LegalEntity": "Vision Corporation",
    "JobCode": null,
    "JobTitle": null,
    "UserStatus": null,
    "PersonType": "EMP",
    "CreateUserAccountFlag": null,
...
}

Create a Sales Manager in a Resource Organization

You can create sales managers and add them to the resource hierarchy. In this example, you create Tom Johnson as a manager of the resource organization North American Sales in the resource parent organization Global HQ. Before executing the steps in this example, make sure that the following prerequisite are already set up:

  • Appropriate business units are set up using the Manage Business Unit task.
  • Appropriate legal entities are set up using the Manage Legal Entity task.
  • E-mail IDs and user accounts are unique.
In this scenario, Tom Johnson is created as an employee resource with the role of SALES_MANAGER. To create him as a sales manager resource:
  1. Construct the request URL for the Create a resource user operation.
  2. Construct the request body with Tom's details.
  3. Use an appropriate REST API client or the cURL command-line utility to make the POST call.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers

cURL Command

curl --user sales_cloud_user -X POST -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers

Request Payload

Here's an example of the request body in JSON format.

{
    "FirstName":"Tom",
    "LastName":"Johnson",
    "ResourceEmail":"tom.johnson@vision.com",
    "HireDate":"2018-08-20",
    "LegalEntity":"Vision Corporation",
    "BusinessUnit":"Vision Corporation Enterprise",
    "ResourceOrgManagerEmail": "resmanager@dnd.vision.com",
    "Username": " TOM.JOHNSON@VISION.COM",
    "ResourceOrgRoleCode":" SALES_MANAGER",
    "ResourceParentOrganizationName": "Global HQ",
    "ResourceOrganizationName": " North American Sales",
    "RawWorkPhoneNumber" : "6504461212",
    "AddressLine1" : "100 Oracle Parkway",
    "City" : "Redwood City",
    "State" : "CA",
    "PostalCode" : "944065",
    "Country" : "US",
}

Note:

Either one of the attributes ResourceOrgManagerEmail or ResourceParentOrganizationName is required. If neither of these is provided, then the root resource organization is defaulted as resource parent organization.

Response Payload

Here's an example of the response body in JSON format.

{
 "PartyName": "Tom Johnson",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "100 Oracle Parkway,REDWOOD CITY, CA 944065",
 "Username": "jdoe",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "Tom",
 "LastName": "Johnson" ,
 "ResourcePartyNumber": "CDRM_765976",
 "State": "CA",
 "ResourceEmail": "tom.johnson@vision.com",
 "RawWorkPhoneNumber": "6505061212",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "100 Oracle Parkway",
 "ResourceOrganizationName": "North American Sales",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_MANAGER",
 "ResourceParentOrganizationName": "Global HQ",
 "ResourceManagerFirstName": "Tom",
 "ResourceManagerLastName": "Johnson",
 "ResourceOrgManagerEmail": "resmanager@dnd.vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": null,
...
}

Create a Sales Representative in a Resource Organization

You can create a sales representative resource and add them to the resource hierarchy. Along with the attributes required for creating a sales representative as a standalone resource, you must specify the additional information such as resource organization's manager e-mail address or parent organization name. In this example, you can find the steps to create a sales representative in a resource organization. Before executing the steps in this example, make sure that the following prerequisite are already set up:

  • Appropriate business units are set up using the Manage Business Unit task.
  • Appropriate legal entities are set up using the Manage Legal Entity task.
  • Email IDs and user names are unique.
Suppose Jane Doe, a new Sales Representative, joins John Smith's organization (JSmithOrg). To create her as a sales representative resource:
  1. Construct the request URL for the Create a resource user operation.
  2. Construct the request body with Jane's details. Providing the user name is optional. If you don't provide the user name, the application will generate the user name by default. Provide values either for the ResourceManagerEmail or the ResourceParentOrganizationName attribute.
  3. Use an appropriate REST API client or the cURL command-line utility to make the POST call.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers

cURL Command

curl --user sales_cloud_user -X POST -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers

Request Payload

Here's an example of the request body in JSON format.

{
    "FirstName":"Jane",
    "LastName":"Doe",
    "ResourceEmail":"jane.doe@dnd.vision.com",
    "HireDate":"2018-08-20",
    "LegalEntity":"Vision Corporation",
    "BusinessUnit":"Vision Corporation Enterprise",
    "ResourceOrgManagerEmail": "resmanager@dnd.vision.com",
    "Username": "jdoe",
    "ResourceOrgRoleCode":"SALES_REPRESENTATIVE",
    "ResourceParentOrganizationName" : "Global HQ",
    "RawWorkPhoneNumber" : "6504461212",
    "AddressLine1" : "100 Oracle Parkway",
    "City" : "Redwood City",
    "State" : "CA",
    "PostalCode" : "944065",
    "Country" : "US",
}

Note:

Either one of the attributes ResourceOrgManagerEmail or ResourceParentOrganizationName is required. If neither of these is provided, then the root resource organization is defaulted as resource parent organization.

Response Payload

Here's an example of the response body in JSON format.


{
 "PartyName": "Jane Doe",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "100 Oracle Parkway,REDWOOD CITY, CA 944065",
 "Username": "jdoe",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "Jane",
 "LastName": "Doe",
 "ResourcePartyNumber": "CDRM_765976",
 "State": "CA",
 "ResourceEmail": "jane.doe@dnd.vision.com",
 "RawWorkPhoneNumber": "6505061212",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "100 Oracle Parkway",
 "ResourceOrganizationName": "JSmithOrg",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_REPRESENTATIVE",
 "ResourceParentOrganizationName" : "Global HQ",
 "ResourceManagerFirstName": "John",
 "ResourceManagerLastName": "Smith",
 "ResourceOrgManagerEmail": "resmanager@dnd.vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": null,
...
}

Remove a Manager from an Organization and Add Another Manager to the Organization

You can replace the manager of an organization using the Resource Users REST API. To replace a manager, you must end-date the existing manager and then create a new sales manager in the organization. Suppose you want to remove Jemmy Hanks from North American Sales Organization as a sales manager and add another manager to the organization. You can do so by specifying the end date of organization membership role using "ResourceOrgMemRoleEndDate" attribute and then create a sales manager in the resource organization.

Note:

Note: An organization cannot have two managers at the same time. Hence, you need to end date organization role membership of the existing manager resource of the target organization before adding the new manager resource to the organization. Alternatively, you may end date the existing manager resource. The date range of organization role membership of managers cannot overlap for same organization. Therefore, if the new manager has to join by tomorrow, you need to remove or end date the existing manager today. For example, if the new manager is required to be added on 2021-01-06, then existing manager Jemmy's role should be end dated on 2021-01-05.

You can end date Jemmy's role by submitting a PATCH request on the REST resource using cURL.

cURL Command

curl --user sales_cloud_user -X PATCH -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/resourceUsers/CDRM_928888

Request Body

{
    "ResourceOrgMemRoleEndDate": "2021-01-05"
}

Response Body

{
    "ResourceProfileId": 300100213939110,
    "PartyName": "Jemmy Hanks",
    "LastUpdateDate": "2021-01-04T14:56:46.656+00:00",
    "LastUpdatedBy": "SALES_ADMIN",
    "CreationDate": "2021-01-04T14:56:36.001+00:00",
    "CreatedBy": "SALES_ADMIN",
    "ResourceType": "INDIVIDUAL",
    "FormattedAddress": null,
    "TimezoneCode": null,
    "Username": "jemmy.hanks@oracle.com",
    "City": null,
    "Country": null,
    "PostalCode": null,
    "UpdateFlag": "true",
    "DeleteFlag": "false",
    "ResourceOrgRoleCode": "SALES_MANAGER",
    "ResourceOrgRoleName": "Sales Manager",
    "FirstName": "Jemmy",
    "LastName": "Hanks",
    "MiddleName": null,
    "Title": "MR.",
    "ResourcePartyNumber": "CDRM_928888",
    "State": null,
    "ResourceEmail": "jemmy.hanks@oracle.com",
    "WorkPhoneCountryCode": null,
    "RawWorkPhoneNumber": null,
    "MobilePhoneCountryCode": null,
    "RawMobilePhoneNumber": null,
    "FaxCountryCode": null,
    "RawFaxNumber": null,
    "AddressLine1": null,
    "AddressLine2": null,
    "ResourceStartDate": "2007-05-01",
    "ResourceEndDate": "4712-12-31",
    "ResourcePartyId": 300100213939111,
    "ResourceOrganizationName": "North American Sales",
    "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
    "ResourceOrgMemRoleEndDate": "2021-01-05",
    "ResourceParentOrganizationName": "Global HQ",
    "ResourceOrgManagerEmail": "sendmail-test-discard@oracle.com",
    "ResourceManagerName": "Sara   King",
    "ResourceManagerFirstName": "Sara ",
    "ResourceManagerLastName": " King",
    "HRManagerEmailAddress": null,
    "HireDate": "2007-05-01",
    "ResourceOrgMemRoleStartDate": "2007-05-01",
    "IndividualRoleCode": "SALES_MANAGER",
    "IndividualRoleStartDate": "2007-05-01",
    "IndividualRoleEndDate": "4712-12-31",
    "ResourceManagerPartyNumber": "100010025532588",
    "County": null,
    "Province": null,
    "ResourceManagerPartyId": 100010025532588,
    "TopResourceFlag": null,
    "PersonNumber": "955160008192781",
    "BusinessUnit": "Vision Corporation Enterprise",
    "LegalEntity": "Vision Corporation",
    "JobCode": null,
    "JobTitle": null,
    "UserStatus": null,
    "PersonType": "EMP",
    "CreateUserAccountFlag": null,

...
}

Retrieve Internal Resources

There are several situations in which you may want to retrieve internal resources. For example, John Smith may want to retrieve a list of his direct reports to review their educational information to determine training needs.

To retrieve one or more internal resources and their information:
  1. Construct the request URL for the appropriate GET operation:
  2. Use an appropriate REST API client or the cURL command-line utility to make the GET call.
Also, you can use finders to retrieve specific internal resources. This use case discusses how to:

For a full list of supported finders, see the documentation for the Resource Users API.

Retrieve an Internal Resource by Email

In this example, you can find the steps to retrieve an internal resource by specifying the email ID in the ResourceEmail finder.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers?q=ResourceEmail='john.smith@dnd.vision.com'

cURL Command

curl --user sales_cloud_user -X GET -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers?q=ResourceEmail='john.smith@dnd.vision.com'

Response Payload

Here's an example of the response body in JSON format.

{
 "PartyName": "John Smith",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "500 Oracle Parkway,REDWOOD CITY, CA 944065",
 "Username": "jsmith439906587",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "John",
 "LastName": "Smith",
 "ResourcePartyNumber": "Conta504976",
 "State": "CA",
 "ResourceEmail": "john.smith@dnd.vision.com",
 "RawWorkPhoneNumber": "6505061212",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "500 Oracle Parkway",
 "ResourceOrganizationName": "JSmithOrg",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_MANAGER",
 "ResourceParentOrganizationName" : "NA Sales",
 "ResourceManagerFirstName": "Phil",
 "ResourceManagerLastName": "Gioco",
 "HRManagerEmailAddress": "hrMan247134917@vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": null,
...
}

Retrieve an Internal Resource by User Name

In this example, you can find the steps to retrieve an internal resource by specifying the user name in the Username finder.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers?q=Username='jdoe439906587'

cURL Command

curl --user sales_cloud_user -X GET -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers?q=Username='jdoe439906587'

Response Payload

{
 "PartyName": "Jane Doe",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "500 Oracle Parkway,REDWOOD CITY, CA 944065",
 "Username": "jdoe439906587",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "John",
 "LastName": "Smith",
 "ResourcePartyNumber": "Conta765976",
 "State": "CA",
 "ResourceEmail": "jane.doe@dnd.vision.com",
 "RawWorkPhoneNumber": "6505061212",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "500 Oracle Parkway",
 "ResourceOrganizationName": "JSmithOrg",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_REPRESENTATIVE",
 "ResourceParentOrganizationName" : "NA Sales",
 "ResourceManagerFirstName": "Phil",
 "ResourceManagerLastName": "Gioco", 
 "HRManagerEmailAddress": "hrMan247134917@vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": null,
...
}

Change the Role of an Internal Resource

You may have to often change the role of internal resources in your organization. The PATCH method lets you change the role of an internal resource. When you change the role of an internal resource, their current role ends and a new membership with a new role begins.

Note:

You can use the Resources Users API to change role of e a resource only in Sales and Fusion Service. You cannot use the API to perform HCM related transactions.
To continue with our example, suppose John Smith has been promoted to the role of Sales VP. Here is how you can go about changing his role:
  1. Construct the request URL for the Update a resource user operation.
  2. Construct the request body by specifying the needed request parameters and their values. You change the role provisioning when you want to promote or demote an internal resource.
  3. Use a REST API client or the cURL command-line utility to make the PATCH call.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta504976

cURL Command

curl --user sales_cloud_user -X PATCH -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta504976

Request Payload

Here's an example of the request body in JSON format.

{
    "ResourceOrgRoleCode":"SALES_VP"
}

Response Payload

Here's an example of the response body in JSON format.

{
 "PartyName": "John Smith",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "500 Oracle Parkway,REDWOOD CITY, CA 944065",
 "Username": "jsmith439906587",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "John",
 "LastName": "Smith",
 "ResourcePartyNumber": "Conta504976",
 "State": "CA",
 "ResourceEmail": "john.smith@dnd.vision.com",
 "RawWorkPhoneNumber": "6505061212",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "500 Oracle Parkway",
 "ResourceOrganizationName": "JSmithOrg",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_VP",
 "ResourceParentOrganizationName" : "NA Sales",
 "ResourceManagerFirstName": "Phil",
 "ResourceManagerLastName": "Gioco",
 "HRManagerEmailAddress": "hrMan247134917@vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": null,
...
}

You can follow a similar method to demote an internal resource. However, if you are demoting a resource that has members in their organization, you must update all the members with a new manager and a resource organization.

For example, when you change role of a Sales Manager to Sales Representative, you must first assign a new manager and an organization to all the members in the Sales Manager's organization. If you do not update the manager and the organization, then the employees in the manager's organization will not have a hierarchy, which in turn could impact the functionality of the organization.

For example, suppose John Smith, a Sales Manager, handles 2 million dollars' worth of opportunities, along with his team. If John Smith is demoted to a Sales Representative, and the sales hierarchy is not re-built, that is if the team members of his old organization are not assigned a new manager and an organization, then the sales report may not correctly reflect the 2 million dollars' worth of opportunities.

Transfer an Internal Resource

Internal resources can move to other organizations within the same organization, because of internal transfers or organizational changes. For example, suppose Katty is transferred from the North Americas sales organization to the global sales organization. How will you go about reflecting this change in Oracle CX Sales and B2B Service using REST APIs?

The ResourceParentOrganizationName indicates the organization hierarchy of an internal resource. Use PATCH to transfer internal resources with the appropriate ResourceParentOrganizationName attribute value. For internal resources with a child hierarchy, you must first move the child hierarchy to another internal resource. If you do not move the child hierarchy, then the child internal resources will not have any hierarchy.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta855676

cURL Command

curl --user sales_cloud_user -X PATCH -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta855676

Request Payload

Here's an example of the request body in JSON format.

{
    "ResourceParentOrganizationName":"GLOBAL_SALES"
}

Response Payload

Here's an example of the response body in JSON format.

{
 "PartyName": "Katty Smith",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "500 Oracle Parkway,REDWOOD CITY, CA 944065",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "Katty",
 "LastName": "Smith",
 "ResourcePartyNumber": "Conta855676",
 "State": "CA",
 "ResourceEmail": "katty.smith@dnd.vision.com",
 "RawWorkPhoneNumber": "6505061212",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "500 Oracle Parkway",
 "ResourceOrganizationName": "KSmithOrg",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_REPRESENTATIVE",
 "ResourceParentOrganizationName" : "GLOBAL_SALES",
 "ResourceManagerFirstName": "Phil",
 "ResourceManagerLastName": "Gioco",
 "HRManagerEmailAddress": "hrMan247134917@vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": null,
...
}

Update Internal Resource Information

Internal resource information can change over the resource's life-cycle. These changes can be frequent, and you have to update the internal resource information in Oracle CX Sales and Fusion Service, to keep it in sync with your third-party application. For example, Katty's work phone number has changed after her transfer to the new organization. You can use the Update a resource user operation (PATCH method) of the Resource Users API to update the information. We recommend that you update only the fields that have changed from the last update.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta855676

cURL Command

curl --user sales_cloud_user -X PATCH -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta855676

Request Payload

Here's an example of the request body in JSON format.

{
    "RawWorkPhoneNumber": "6505061409"
}

Response Payload

Here's an example of the response body in JSON format.

{
 "PartyName": "Katty Smith",
 "ResourceType": "INDIVIDUAL",
 "FormattedAddress": "500 Oracle Parkway,REDWOOD CITY, CA 944065",
 "City": "Redwood City",
 "Country": "US",
 "PostalCode": "944065",
 "FirstName": "Katty",
 "LastName": "Smith",
 "ResourcePartyNumber": "Conta855676",
 "State": "CA",
 "ResourceEmail": "katty.smith@dnd.vision.com",
 "RawWorkPhoneNumber": "6505061409",
 "RawMobilePhoneNumber": null,
 "RawFaxNumber": null,
 "AddressLine1": "500 Oracle Parkway",
 "ResourceOrganizationName": "KSmithOrg",
 "ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
 "ResourceOrgMemRoleEndDate": "4712-12-31",
 "ResourceOrgRoleCode":"SALES_REPRESENTATIVE",
 "ResourceParentOrganizationName" : "GLOBAL_Sales",
 "ResourceManagerFirstName": "Phil",
 "ResourceManagerLastName": "Gioco",
 "HRManagerEmailAddress": "hrMan247134917@vision.com",
 "HireDate": "2018-08-20",
 "ResourceOrgMemRoleStartDate": "2018-08-20",
 "ResourceManagerPartyNumber": "100010034246635",
 "ResourceManagerPartyId": 100010034246635,
 "PersonNumber": "300100159661235",
 "BusinessUnit": "Vision Corporation Enterprise",
 "LegalEntity": "Vision Corporation",
 "UserStatus": "A",
 "PersonType": "EMP",
 "CreateUserAccountFlag": null,
...
}

End-Date an Internal Resource

Sometimes, you may have to end-date an internal resource. This may be because of resource resignation, contract expiration, or resource transfer to a non-sales organization.

Note:

A contract expiry does not invoke an HR transaction.

For example, let's say you want to set the end date of Diane Cho to 31-Jun-2019. You update the ResourceEndDate attribute of the resource with the date. This does not delete the record of the internal resource, but only removes the usage on the end date.

For internal resources with a child hierarchy, you must ensure that the child hierarchy moves to another resource before the end date. If you do not move the child resources, then they will not have a hierarchy and this will result in errors. For example, Nelon Pascal is a sales manager who has two sales representatives, Neya Pali and Carlton Baugh, reporting to him. Nelon Pascal resigns from Vision Corporation and his resource assignment is end-dated. When you end-date a manager without replacement, the transactions within the manger's organization are not visible. You must assign a new manager to the organization for the transactions to be visible. Before Nelon's resource assignment is end dated, Oracle recommends that you move his reports to a different manager such as Nelon's manager, Jane Reifer. You can retrieve the ResourcePartyNumber for a resource by using a finder to search the resource. When you end-date a resource who owns transactions, you must transfer the resource’s transactions to another active resource. For more information about transfering transactions to other users, see the Implementing Sales guide.

When you end-date an internal resource, depending on the conditions, the following changes could take place,
  • The user login of the internal resource may be suspended if there are no roles provisioned to the user after the resource end-date.
  • End-dating an internal resource only end-dates job roles mapped to the resource roles.
  • If the internal resource has been assigned other roles that are independent of resource roles, then end-dating such a resource would not suspend the user account.
  • End-dated resources will not be available as members or owners of transaction objects such as Account, Opportunity, and so on.
  • End-dating an internal resource does not end-date the work assignment, nor is the worker's work relationship terminated.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta765982

cURL Command

curl --user sales_cloud_user -X PATCH -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta765982

Request Payload

Here's an example of the request body in JSON format.

{
    "ResourceEndDate": "2019-06-31"
}

Response Payload

Here's an example of the response body in JSON format.

{
"ResourceProfileId": 300100159661456,
"PartyName": "Diane Cho",
"LastUpdateDate": "2018-08-20T18:34:56.289+00:00",
"LastUpdatedBy": "SALES_ADMIN",
"CreationDate": "2018-08-20T18:34:29.001+00:00",
"CreatedBy": "SALES_ADMIN",
"ResourceType": "INDIVIDUAL",
"FormattedAddress": "100 Market Street,SAN FRANCISCO, CA 94105",
"TimezoneCode": null,
"Username": "dcho",
"City": "San Francisco",
"Country": "US",
"PostalCode": "94105",
"UpdateFlag": "true",
"DeleteFlag": "false",
"FirstName": "Diane",
"LastName": "Cho",
"MiddleName": null,
"Title": null,
"ResourcePartyNumber": "Conta765982",
"State": "CA",
"ResourceEmail": "diane.cho@dnd.vision.com",
"RawWorkPhoneNumber": "4155551212",
"RawMobilePhoneNumber": null,
"RawFaxNumber": null,
"AddressLine1": "100 Market Street",
"AddressLine2": null,
"ResourceStartDate": "2018-08-20",
"ResourceEndDate": "2019-06-31",
"ResourcePartyId": 300100159661457,
"ResourceOrganizationName": "NA Sales",
"ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
"ResourceOrgMemRoleEndDate": "4712-12-31",
"ResourceOrgRoleCode": "SALES_REPRESENTATIVE",
"ResourceParentOrganizationName": "NA Sales",
"ResourceOrgManagerEmail": "CEO.CRM+TM40@ap6023fems.us.vision.com",
"ResourceManagerName": null,
"ResourceManagerFirstName": "Phil",
"ResourceManagerLastName": "Gioco",
"HRManagerEmailAddress": "hrMan247134917@vision.com",
"HireDate": "2018-08-20",
"ResourceOrgMemRoleStartDate": "2018-08-20",
"ResourceManagerPartyNumber": "100010034246635",
"County": null,
"Province": null,
"ResourceManagerPartyId": 100010034246635,
"PersonNumber": "300100159661466",
"BusinessUnit": "Vision Corporation Enterprise",
"LegalEntity": "Vision Corporation",
"JobCode": null,
"JobTitle": null,
"UserStatus": "I",
"PersonType": "EMP",
...
}

Suspend a User Account

There are times when you want to suspend an internal resource account for a certain period of time instead of end-dating them. For example, Diane Cho's contract has expired and her account has to be temporarily suspended. You can suspend an internal user account by setting the UserStatus attribute for the user, using the PATCH method. You can suspoend an internal resource account only when there are no validation errors, as the Resource Users REST API validates the entire resource object before suspending the account. When you suspend an internal resource, there is no change to the user's current role but the user will not be able to login.

Note:

Use the following process if you wish to suspend an internal resource's account and also change any resource attributes. If you wish to simply suspend a user account and not change any resource attributes, then use the Users REST API .

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta765982

cURL Command

curl --user sales_cloud_user -X PATCH -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta765982

Request Payload

Here's an example of the request body in JSON format.

{
    "UserStatus" : "S"
}

Response Payload

Here's an example of the response body in JSON format.

{
"ResourceProfileId": 300100159661456,
"PartyName": "Diane Cho",
"LastUpdateDate": "2018-08-20T18:34:56.289+00:00",
"LastUpdatedBy": "SALES_ADMIN",
"CreationDate": "2018-08-20T18:34:29.001+00:00",
"CreatedBy": "SALES_ADMIN",
"ResourceType": "INDIVIDUAL",
"FormattedAddress": "100 Market Street,SAN FRANCISCO, CA 94105",
"TimezoneCode": null,
"Username": "dcho",
"City": "San Francisco",
"Country": "US",
"PostalCode": "94105",
"UpdateFlag": "true",
"DeleteFlag": "false",
"FirstName": "Diane",
"LastName": "Cho",
"MiddleName": null,
"Title": null,
"ResourcePartyNumber": "Conta765982",
"State": "CA",
"ResourceEmail": "diane.cho@dnd.vision.com",
"RawWorkPhoneNumber": "4155551212",
"RawMobilePhoneNumber": null,
"RawFaxNumber": null,
"AddressLine1": "100 Market Street",
"AddressLine2": null,
"ResourceStartDate": "2018-08-20",
"ResourceEndDate": "2019-01-31",
"ResourcePartyId": 300100159661457,
"ResourceOrganizationName": "NA Sales",
"ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
"ResourceOrgMemRoleEndDate": "4712-12-31",
"ResourceOrgRoleCode": "SALES_REPRESENTATIVE",
"ResourceParentOrganizationName": "NA Sales",
"ResourceOrgManagerEmail": "CEO.CRM+TM40@ap6023fems.us.vision.com",
"ResourceManagerName": null,
"ResourceManagerFirstName": "Phil",
"ResourceManagerLastName": "Gioco",
"HRManagerEmailAddress": "hrMan247134917@vision.com",
"HireDate": "2018-08-20",
"ResourceOrgMemRoleStartDate": "2018-08-20",
"ResourceManagerPartyNumber": "100010034246635",
"County": null,
"Province": null,
"ResourceManagerPartyId": 100010034246635,
"PersonNumber": "300100159661466",
"BusinessUnit": "Vision Corporation Enterprise",
"LegalEntity": "Vision Corporation",
"JobCode": null,
"JobTitle": null,
"UserStatus": "S",
"PersonType": "EMP",
...
}

Reactivate a User Account

You can reactivate a suspended user account by simply setting the UserStatus attribute to A. For example, to reactivate Diane Cho's user account after her contract has been renewed.

Example Request URL

Use this resource URL format.

https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta765982

cURL Command

curl --user sales_cloud_user -X PATCH -d @example_request_payload.json https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.19.01/resourceUsers/Conta765982

Request Payload

Here's an example of the request body in JSON format.

{
    "UserStatus" : "A"
}

Response Payload

Here's an example of the response body in JSON format.

{
"ResourceProfileId": 300100159661456,
"PartyName": "Diane Cho",
"LastUpdateDate": "2018-08-20T18:34:56.289+00:00",
"LastUpdatedBy": "SALES_ADMIN",
"CreationDate": "2018-08-20T18:34:29.001+00:00",
"CreatedBy": "SALES_ADMIN",
"ResourceType": "INDIVIDUAL",
"FormattedAddress": "100 Market Street,SAN FRANCISCO, CA 94105",
"TimezoneCode": null,
"Username": "dcho",
"City": "San Francisco",
"Country": "US",
"PostalCode": "94105",
"UpdateFlag": "true",
"DeleteFlag": "false",
"FirstName": "Diane",
"LastName": "Cho",
"MiddleName": null,
"Title": null,
"ResourcePartyNumber": "Conta765982",
"State": "CA",
"ResourceEmail": "diane.cho@dnd.vision.com",
"RawWorkPhoneNumber": "4155551212",
"RawMobilePhoneNumber": null,
"RawFaxNumber": null,
"AddressLine1": "100 Market Street",
"AddressLine2": null,
"ResourceStartDate": "2018-08-20",
"ResourceEndDate": "2019-01-31",
"ResourcePartyId": 300100159661457,
"ResourceOrganizationName": "NA Sales",
"ResourceOrganizationUsage": "SALES_RESOURCE_ORG",
"ResourceOrgMemRoleEndDate": "4712-12-31",
"ResourceOrgRoleCode": "SALES_REPRESENTATIVE",
"ResourceParentOrganizationName": "NA Sales",
"ResourceOrgManagerEmail": "CEO.CRM+TM40@ap6023fems.us.vision.com",
"ResourceManagerName": null,
"ResourceManagerFirstName": "Phil",
"ResourceManagerLastName": "Gioco",
"HRManagerEmailAddress": "hrMan247134917@vision.com",
"HireDate": "2018-08-20",
"ResourceOrgMemRoleStartDate": "2018-08-20",
"ResourceManagerPartyNumber": "100010034246635",
"County": null,
"Province": null,
"ResourceManagerPartyId": 100010034246635,
"PersonNumber": "300100159661466",
"BusinessUnit": "Vision Corporation Enterprise",
"LegalEntity": "Vision Corporation",
"JobCode": null,
"JobTitle": null,
"UserStatus": "A",
"PersonType": "EMP",
...
}