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 thefileName
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.
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 theresourceType
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 theid
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 theid
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 theid
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.
{
"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"
}
]
}