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:

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.

Response codes

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.

Response codes

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.

Response codes

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.

Response codes

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.

Response codes

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.

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.

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:

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.

Response codes

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.

Response codes

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.

Response codes

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.

Response codes

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.

Response codes

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.

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.

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: