Search

Skip to end of metadata
Go to start of metadata

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:

  1. 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.
  2. 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

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/create 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

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 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:

  • PENDING
  • RUNNING
  • FAILED
  • FINISHED
  • FINISHED_WITH_ERRORS
  • FINISHED_WITH_RESULT

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:

  • No labels