REST API for Oracle Identity Cloud Service

Importing Using the REST API

This section provides example requests and responses when you want to import users, groups, and approles into your environment using the Oracle Identity Cloud Service REST API.

The following sections walk you through the steps:

Note:

To safely handle the import of the CSV file to Oracle Identity Cloud Service, if any cell values are escaped to avoid CSV injection, the quotes are removed. For example, during import if the cell value is '@test', the actual value will be @test.

At: @
Plus: +
Minus: -
Equals to: =
Pipe: |
Percentage: %

Import the CSV File to Storage

To import the CSV file to storage, send a POST request to the /storage/v1/Files endpoint.

Note:

See Importing and Exporting Users, Groups, and AppRoles for more information on the CSV file.

Parameter	Description
`fileName`	Enter the name that you want the file to have when you save it to storage.
`isPublic`	Indicates whether the file is private or public. Currently, only private files are supported. Set this value to `false.`
`contentType`	Files are limited to a `contentType` of `text/csv` or `application/directory.`
`file`	Enter the name of file that you want to upload.

Example Request

$ curl
-X POST
-H "Authorization: Bearer <Access Token Value>"
-H "Cache-Control: no-cache"
-H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
-F "fileName=UsersImp1.csv"
-F "contentType=text/csv"
-F "isPublic=false"
-F file=@"C:/examplefilelocation/Users1.csv" "https://tenant-base-url/storage/v1/Files"

Example Response

Note:

Make note of the fileName value (bold in the example response).

{
  "fileName":"files/201608261841/Users1.csv",
  "isPublic":false,
  "fileUrl":"https://tenant-base-url/v1/Storage-example2/90C63D43D7E226D7A8C5E9F8BF7A24291FA5876BDC413AF9F37A3D94B8A02C5F/files/201608261841/Users1.csv"
}

Schedule the Job to Import the CSV File into Your Environment

To create a scheduled job, send a POST request to the /job/v1/JobSchedules endpoint. In the JSON example request body below, for resource specific jobType imports, the value for jobType can be UserImport, GroupImport, or AppRoleImport, depending on the type of data that you are trying to import.

There is also a generic import option available where the value for jobType is Import, and then the attribute resourceType is added and the values can be User, Group, or Grant (for AppRole), depending on the type of data that you are trying to import.

Note:

Use of the resourceType of AppRole for import is not supported.

The examples below show both the resource specific jobType import and the generic import options.

Example Request for Resource Specific jobType Import

$ curl
-X POST
-H "Content-Type: application/scim+json"
-H "Authorization: Bearer <Access Token Value>"
-H "Cache-Control: no-cache" -d '{
   "schemas": [
     "urn:ietf:params:scim:schemas:oracle:idcs:JobSchedule"
   ],
  "jobType": "UserImport",
   "runNow": true,
   "parameters": [
    {
      "name": "fileLocation",
      "value": "files/201608261841/UsersImp1.csv"
     },
    {
       "name": "fileType",
       "value": "csv"
     }
   ]
 }' "https://tenant-base-url/job/v1/JobSchedules"

An additional parameter is required for the AppRoleImport jobType:

{
  "name": "appDisplayName",
  "value": "MyApp"
}

Example Response for Resource Specific jobType Import

Note:

Make note of the id value (bold in the example response). This is the value for the jobScheduleid that you specify in the next section.

{
  "id": "ffecd68a-fc08-4177-8afc-84a1d523b911",
  "jobType": "UserImport",
  "nextFireTime": "2016-08-26T18:42:19.883Z",
  "runAt": "2016-08-26T18:42:19.883Z",
  "parameters": [
    {
      "name": "fileLocation",
      "value": "files/201608261841/Users1.csv"
    },
    {
      "name": "fileType",
      "value": "csv"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:JobSchedule"
  ]
}

Example Request for Generic Import

$ curl
-X POST
-H "Content-Type: application/scim+json"
-H "Authorization: Bearer <Access Token Value>"
-H "Cache-Control: no-cache" -d '{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:JobSchedule"
  ],
  "jobType": "Import",
  "runNow": true,
  "parameters": [
    {
      "name": "fileLocation",
      "value": "files/201608261841/UsersImp1.csv"
    },
    {
      "name": "fileType",
      "value": "csv"
    },
    {
      "name": "resourceType",
      "value": "User"
    }
  ]
}' "https://tenant-base-url/job/v1/JobSchedules"

An additional parameter is required for the Grant ResourceType:

{
  "name": "appDisplayName",
  "value": "MyApp"
}

Example Response for Generic Import

Note:

Make note of the id value (bold in the example response). This is the value for the jobScheduleid that you specify in the next section.

{
  "id": "ffecd68a-fc08-4177-8afc-84a1d523b911",
  "jobType": "Import",
  "nextFireTime": "2016-08-26T18:42:19.883Z",
  "runAt": "2016-08-26T18:42:19.883Z",
  "parameters": [
    {
      "name": "fileLocation",
      "value": "files/201608261841/Users1.csv"
    },
    {
      "name": "fileType",
      "value": "csv"
    },
    {
      "name": "resourceType",
      "value": "User"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:JobSchedule"
  ]
}

Verify That the Job Was Successful

To verify that the import job succeeded, send a GET request to the /job/v1/JobHistories endpoint using jobScheduleid as the identifier.

Example Request

$  curl
- X GET
- H "Content-Type: application/json"
- H "Authorization: Bearer Access Token Value"
- H "Cache-Control: no-cache"
"https://tenant-base-url/job/v1/JobHistories?filter=jobScheduleid%20eq%20%22ffecd68a-fc08-4177-8afc-84a1d523b911%22"

Example Response

Note:

Make note of the id value (bold in the example response). This is the value for the historyId that you specify in the next section.

{
  "schemas": [
    "urn:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {
      "endTime": "2016-08-26T18:42:21.878Z",
      "jobType": "UserImport",
      "failureCount": 0,
      "successCount": 5,
      "percentage": 100,
      "status": "succeeded",
      "jobDisplayName": "User File Import Job",
      "startTime": "2016-08-26T18:42:19.883Z",
      "jobDisplayId": "44",
      "jobScheduleId": "ffecd68a-fc08-4177-8afc-84a1d523b911",
      "jobDescription": "A job for importing users into IDCS from a file",
      "instanceId": "qa1siteb-2105-jobsv1-114718228563211471822859774",
      "totalCount": 5,
      "id": "2071a27f549843a48e00cadbb8f4364e",
      "meta": {
        "created": "2016-08-26T18:42:19.973Z",
        "lastModified": "2016-08-26T18:42:21.889Z",
        "resourceType": "JobHistory",
        "location": "https://tenant-base-url/job/v1/JobHistories/2071a27f549843a48e00cadbb8f4364e"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:JobHistory"
      ],
      "idcsCreatedBy": {
        "value": "3f461931ecde403c85bf367379b417d3",
        "display": "admin opc",
        "type": "User",
        "$ref": "https://tenant-base-url/admin/v1/Users/3f461931ecde403c85bf367379b417d3"
      },
      "idcsLastModifiedBy": {
        "value": "3f461931ecde403c85bf367379b417d3",
        "display": "admin opc",
        "type": "User",
        "$ref": "https://tenant-base-url/admin/v1/Users/3f461931ecde403c85bf367379b417d3"
      }
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 50
}

Review the Job Report

To review the status of the import job, send a GET request to the /job/v1/JobReports endpoint using historyId as the identifier. If there are any failures in the import process, it lists those failures in the form of a CSV file in storage.

curl
-X GET
-H "Authorization: Bearer <AccessToken>"
-H "Cache-Control: no-cache"
"https://tenant-base-url/job/v1/JobReports?filter=historyId%20eq%20%2071a27f549843a48e00cadbb8f4364e"

When There Are Errors

If you encounter errors during a bulk load operation and you cannot fix them by modifying the entries in the import file, you can set a diagnostics level to capture operational logs during the bulk load operation. You can then view those logs to help you to determine the cause of the problem. See the Running the Diagnostic Data Report section in the Administering Oracle Identity Cloud Service guide for more information.

If you encounter errors after a bulk load operation, use the Jobs page to help you resolve the errors.

Access the Jobs page by clicking Jobs in the Identity Cloud Service console.
Click View Details for the failed job.
Click Export Errors, and then download the exported error file.
Open the comma-separated value error file using any .csv file manager, such as Microsoft Excel. The exported file contains all the failed rows, as well as the failure reason in the Error Message column.
Correct the errors, and then remove the Type and Error Message columns from the file.
Re-import the file.

See the Viewing Jobs and Job Details section in the Administering Oracle Identity Cloud Service guide for more information.

Replacing Existing Values to Compex Multi-Valued Attributes (CMVA)

When administrators update users by using Import, by default new values will be added to existing multi-valued attributes.

For example, say that a user has set her work email to alice@myservice.invalid. Email is a multi-valued attribute, and when an administrator imports a CSV file with the updated email value (for example administrator@myservice.invalid), the new email is added to the existing instance of email, and both the values are saved.

You can also update the email values. For example, to update the email value to alice1@myservice.invalid, pass the replaceExistingMultiValuedValues attribute when scheduling an Import job.

Sample JSON payload:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:JobSchedule"
  ],
  "jobType": "UserImport",
  "runNow": true,
  "parameters": [
    {
      "name": "fileLocation",
      "value": "files/202003260936/User.csv"
    },
    {
      "name": "fileType",
      "value": "csv"
    },
    {
      "name": "replaceExistingMultiValuedValues",
      "value": "true"
    }
  ]
}