API bulk operations
The account management section covered how to manage individual accounts. It is also possible to perform operations on multiple accounts by making a single ‘bulk’ request to the API. Not all operations and accounts types are supported in bulk mode – currently only personal accounts with no admin roles may be managed in this way.
There are two styles of bulk operations:
- Applying a ‘template’ to a set of accounts. This is used to make a consistent change to a known set of accounts. For instance, it may be used to update the value of a single attribute to multiple accounts without having to make multiple calls to the API.
- Processing an account list from a .csv file. This may be used to create, modify or delete multiple accounts by using data input from a spreadsheet. The .csv file may be exported from a spreadsheet application such as Microsoft Excel. A template .xlsx file may be obtained from the OpenAthens administration site (https://admin.openathens.net). See Bulk template
Creating new accounts via a .csv upload
Prerequisites
To create new accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be created, as described in the organisations section.
- have a .csv file containing account information, formatted according to the upload template as described above.
Procedure
To create accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with text/csv data.
/api/v1/example.org/organisation/<id>/bulk/create/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object. This indicates that the bulk request has been accepted is running as a task. The task object may be subsequently polled by following the ‘self’ link from the response.
Example
Request:
POST /api/v1/example.org/organisation/12345/bulk/create/personal?sendEmail=true HTTP/1.1
Authorization: OAApiKey <api-key>
Content-Type: text/csv
... detail omitted
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.task-v1+json
{
"id" : "67890",
"type" : "ACCOUNT_CREATE",
"creationTime" : "2014-02-17T10:31:03Z",
"errors" : { },
"message" : "Update accounts",
"parentId" : "12345",
"percentComplete" : 0,
"status" : "RUNNING",
"links" : [ {
"href" : "/api/v1/example.org/task/67890",
"rel" : "self",
"type" : "application/vnd.eduserv.iam.admin.task-v1+json",
"method" : "get"
} ]
}
Modifying accounts via a .csv upload
Prerequisites
To modify accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be modified, as described in Fetching organisations via the API.
- obtain one or more account ids via the account query or other API.
- have a .csv file containing account information, formatted according to the upload template, as described above.
Procedure
To modify accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with text/csv data.
/api/v1/example.org/organisation/<id>/bulk/modify/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object.
Deleting accounts via a .csv upload
Prerequisites
To delete accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be deleted, as described in Fetching organisations via the API.
- obtain one or more account ids via the account query or other API.
- have a .csv file containing account information, formatted according to the upload template, as described above.
Procedure
To delete accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with text/csv data.
/api/v1/example.org/organisation/<id>/bulk/delete/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object.
Modifying accounts via a request template
In addition to performing requests based on an .csv file, it is also possible to apply an account ‘template’ to a set of existing accounts. The template is used to make a consistent change to a large number of accounts, without the need to a separate call to the API for each account in question.
Prerequisites
To modify accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be created, as described in Fetching organisations via the API.
- obtain one or more account ids via the account query or other API.
Procedure
To modify accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with a application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json
object in the request body.
/api/v1/example.org/organisation/<id>/bulk/modify/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object.
Example
Request:
POST /api/v1/example.org/organisation/12345/bulk/modify/personal HTTP/1.1
Authorization: OAApiKey <api-key>
Content-Type: application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json
{
"template" : {
"attributes" : {
"jobRole" : "Managers"
}
},
"accountIds": ["546464"]
}
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.task-v1+json
{
"id" : "67890",
"type" : "ACCOUNT_MODIFY",
"creationTime" : "2014-02-17T10:31:03Z",
"errors" : { },
"message" : "Update accounts",
"parentId" : "12345",
"percentComplete" : 0,
"status" : "RUNNING",
"links" : [ {
"href" : "/api/v1/example.org/task/67890",
"rel" : "self",
"type" : "application/vnd.eduserv.iam.admin.task-v1+json",
"method" : "get"
} ]
}
Deleting accounts via a request template
A request template may also be used to delete a large number of accounts in a single request.
Prerequisites
To modify accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be created, as described in Fetching organisations via the API.
- obtain one or more account ids via the account query or other API.
Procedure
To delete accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with a application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json
object in the request body.
/api/v1/example.org/organisation/<id>/bulk/delete/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object.
Example
Request:
POST /api/v1/example.org/organisation/12345/bulk/delete/personal HTTP/1.1
Authorization: OAApiKey <api-key>
Content-Type: application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json
{
"accountIds": ["546464"]
}
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.task-v1+json
{
"id" : "67890",
"type" : "ACCOUNT_DELETE",
"creationTime" : "2014-02-17T10:31:03Z",
"errors" : { },
"message" : "Update accounts",
"parentId" : "12345",
"percentComplete" : 0,
"status" : "RUNNING",
"links" : [ {
"href" : "/api/v1/example.org/task/67890",
"rel" : "self",
"type" : "application/vnd.eduserv.iam.admin.task-v1+json",
"method" : "get"
} ]
}
application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json object
This type represents a request to perform a template-based bulk operation to a set of accounts.
Object field | Description |
---|---|
template | The template to apply. This is an application/vnd.eduserv.iam.admin.accountRequest-v1+json object. Note however, that not all operations are supported. |
accountIds | A list of account ids to perform the template to. |
application/vnd.eduserv.iam.admin.task-v1+json object
This type represents a background task. It indicates the status of the task, an estimate of its progress and any errors that may have occurring during processing. Tasks may be periodically polled by a client application in order to be able to monitor their progress.
Object field | Description |
---|---|
id | The unique identifier for this task. |
type | The type of operation being performed. |
creationTime | The time the task was created. |
errors | A list of errors that may have occurred (if status = FINISHED_WITH_ERRORS). |
message | A description of the task. |
percentComplete | An indication of the progress of the task. |
status | The status of the task. This may be one of:
|
Command-line tools for performing uploads
It is possible to perform a bulk-operation by invoking a single command from a Linux terminal or from cmd.exe on Windows. To do this you can use most HTTP clients that can be run from the command line. We will use cURL in our examples because it is available for most platforms, including Windows.
Prerequisites
To delete accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be deleted, as described in the organisations section.
- obtain one or more account ids via the account query or other API.
- have a .csv file containing account information, formatted according to the upload template, as described in one of the earlier sections.
Response payload
The response should be sent to one of the URLs defined in the previous sections, using the following command
curl -v -u{admin_account}:{admin_password} -XPOST -H'Content-type: text/csv' -T{csv_file} {request_url}
Where admin_account and admin_password are an administrator username and password, csv_file is the path to the file to upload and request_url is the request location.
Example
curl -v -umyaccount:abc123 -XPOST -H'Content-type: text/csv' -T./my_upload.csv https://admin.openathens.net/api/v1/example.org/organisation/12345/bulk/create/personal
See also:
The account management section covered how to manage individual accounts. It is also possible to perform operations on multiple accounts by making a single ‘bulk’ request to the API. Not all operations and accounts types are supported in bulk mode – currently only personal accounts may be managed in this way.
There are two styles of bulk operations:
- Applying a ‘template’ to a set of accounts. This is used to make a consistent change to a known set of accounts. For instance, it may be used to update the value of a single attribute to multiple accounts without having to make multiple calls to the API.
- Processing an account list from a .csv file. This may be used to create, modify or delete multiple accounts by using data input from a spreadsheet. The .csv file may be exported from a spreadsheet application such as Microsoft Excel. A template .xlsx file may be obtained from the OpenAthens administration site (https://admin.openathens.net). See Bulk template
Creating new accounts via a .csv upload
Prerequisites
To create new accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be created, as described in the organisations section.
- have a .csv file containing account information, formatted according to the upload template as described above.
Procedure
To create accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with text/csv data.
/api/v1/example.org/organisation/<id>/bulk/create/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object. This indicates that the bulk request has been accepted is running as a task. The task object may be subsequently polled by following the ‘self’ link from the response.
Example
Request:
POST /api/v1/example.org/organisation/12345/bulk/create/personal?sendEmail=true HTTP/1.1
Authorization: OAApiKey <api-key>
Content-Type: text/csv
... detail omitted
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.task-v1+json
{
"id" : "67890",
"type" : "ACCOUNT_CREATE",
"creationTime" : "2014-02-17T10:31:03Z",
"errors" : { },
"message" : "Update accounts",
"parentId" : "12345",
"percentComplete" : 0,
"status" : "RUNNING",
"links" : [ {
"href" : "/api/v1/example.org/task/67890",
"rel" : "self",
"type" : "application/vnd.eduserv.iam.admin.task-v1+json",
"method" : "get"
} ]
}
Modifying accounts via a .csv upload
Prerequisites
To modify accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be modified, as described in Fetching organisations via the API.
- obtain one or more account ids via the account query or other API.
- have a .csv file containing account information, formatted according to the upload template, as described above.
Procedure
To modify accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with text/csv data.
/api/v1/example.org/organisation/<id>/bulk/modify/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object.
Deleting accounts via a .csv upload
Prerequisites
To delete accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be deleted, as described in Fetching organisations via the API.
- obtain one or more account ids via the account query or other API.
- have a .csv file containing account information, formatted according to the upload template, as described above.
Procedure
To delete accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with text/csv data.
/api/v1/example.org/organisation/<id>/bulk/delete/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object.
Modifying accounts via a request template
In addition to performing requests based on an .csv file, it is also possible to apply an account ‘template’ to a set of existing accounts. The template is used to make a consistent change to a large number of accounts, without the need to a separate call to the API for each account in question.
Prerequisites
To modify accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be created, as described in Fetching organisations via the API.
- obtain one or more account ids via the account query or other API.
Procedure
To modify accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with a application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json
object in the request body.
/api/v1/example.org/organisation/<id>/bulk/modify/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object.
Example
Request:
POST /api/v1/example.org/organisation/12345/bulk/modify/personal HTTP/1.1
Authorization: OAApiKey <api-key>
Content-Type: application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json
{
"template" : {
"attributes" : {
"jobRole" : "Managers"
}
},
"accountIds": ["546464"]
}
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.task-v1+json
{
"id" : "67890",
"type" : "ACCOUNT_MODIFY",
"creationTime" : "2014-02-17T10:31:03Z",
"errors" : { },
"message" : "Update accounts",
"parentId" : "12345",
"percentComplete" : 0,
"status" : "RUNNING",
"links" : [ {
"href" : "/api/v1/example.org/task/67890",
"rel" : "self",
"type" : "application/vnd.eduserv.iam.admin.task-v1+json",
"method" : "get"
} ]
}
Deleting accounts via a request template
A request template may also be used to delete a large number of accounts in a single request.
Prerequisites
To modify accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be created, as described in Fetching organisations via the API.
- obtain one or more account ids via the account query or other API.
Procedure
To delete accounts underneath a given organisation, perform an HTTP POST the following URL, sending a request body with a application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json
object in the request body.
/api/v1/example.org/organisation/<id>/bulk/delete/<type>
Where id is the organisation ID and type is the type of account being modified. Currently only personal is supported.
Request querystring
The following querystring parameters affect the behaviour of the operation.
Querystring Parameter | Description |
---|---|
sendEmail | A Boolean indicating whether to send an email to the user if the operation was successful or unsuccessful. |
Response codes
Response code | Description |
---|---|
202 | The request was successful the upload was accepted for processing. |
400 | The request is invalid. |
Response payload
The response payload is an application/vnd.eduserv.iam.admin.task-v1+json
object.
Example
Request:
POST /api/v1/example.org/organisation/12345/bulk/delete/personal HTTP/1.1
Authorization: OAApiKey <api-key>
Content-Type: application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json
{
"accountIds": ["546464"]
}
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.task-v1+json
{
"id" : "67890",
"type" : "ACCOUNT_DELETE",
"creationTime" : "2014-02-17T10:31:03Z",
"errors" : { },
"message" : "Update accounts",
"parentId" : "12345",
"percentComplete" : 0,
"status" : "RUNNING",
"links" : [ {
"href" : "/api/v1/example.org/task/67890",
"rel" : "self",
"type" : "application/vnd.eduserv.iam.admin.task-v1+json",
"method" : "get"
} ]
}
application/vnd.eduserv.iam.admin.bulkAccountRequest-v1+json object
This type represents a request to perform a template-based bulk operation to a set of accounts.
Object field | Description |
---|---|
template | The template to apply. This is an application/vnd.eduserv.iam.admin.accountRequest-v1+json object. Note however, that not all operations are supported. |
accountIds | A list of account ids to perform the template to. |
application/vnd.eduserv.iam.admin.task-v1+json object
This type represents a background task. It indicates the status of the task, an estimate of its progress and any errors that may have occurring during processing. Tasks may be periodically polled by a client application in order to be able to monitor their progress.
Object field | Description |
---|---|
id | The unique identifier for this task. |
type | The type of operation being performed. |
creationTime | The time the task was created. |
errors | A list of errors that may have occurred (if status = FINISHED_WITH_ERRORS). |
message | A description of the task. |
percentComplete | An indication of the progress of the task. |
status | The status of the task. This may be one of:
|
Command-line tools for performing uploads
It is possible to perform a bulk-operation by invoking a single command from a Linux terminal or from cmd.exe on Windows. To do this you can use most HTTP clients that can be run from the command line. We will use cURL in our examples because it is available for most platforms, including Windows.
Prerequisites
To delete accounts, a client application must
- authenticate to the API as described in Authenticating to the API.
- obtain an organisation object for the organisation under which the account should be deleted, as described in the organisations section.
- obtain one or more account ids via the account query or other API.
- have a .csv file containing account information, formatted according to the upload template, as described in one of the earlier sections.
Response payload
The response should be sent to one of the URLs defined in the previous sections, using the following command
curl -v -u{admin_account}:{admin_password} -XPOST -H'Content-type: text/csv' -T{csv_file} {request_url}
Where admin_account and admin_password are an administrator username and password, csv_file is the path to the file to upload and request_url is the request location.
Example
curl -v -umyaccount:abc123 -XPOST -H'Content-type: text/csv' -T./my_upload.csv https://admin.openathens.net/api/v1/example.org/organisation/12345/bulk/create/personal
See also: