RESTful User Provisioning with IBM Business Process Manager on Cloud

RESTful User Provisioning with IBM Business
Process Manager on Cloud
The APIs described in this document are currently being used by
the BPM on Cloud team.
RESTful User Provisioning with IBM Business
Process Manager on Cloud
Have you ever wanted to add a very large number of users to your IBM Business Process
Manager on Cloud subscription? What about automatically de-provisioning a user when
they move on to other projects or businesses? The manual on-boarding experience and
behavior for IBM Business Process Manager on Cloud is great when you want to quickly
establish a small team of users with the same level of access rights, but does not scale
well when you need to extend adoption of IBM Business Process Manager on Cloud
throughout a much larger organization. Thankfully IBM Business Process Manager on
Cloud provides a RESTful web service for adding, deleting, and querying users. This
document describes the technical details of this service and provides simple samples that
illustrate how to leverage the service.
Business Process Manager on Cloud provides a single URI endpoint that any account
administrator can authenticate with, and perform simple user queries, user provisioning
and user de-provisioning requests. The ‘Service Overview’ table below, as well as the
method descriptions that follow, provide all the technical details required for working
with the service.
Service Overview
Subject
Details
URL Endpoint
Authentication
Data Mime type
Access restrictions
Query Method
Add Method
Delete method
https://<vhost>.bpm.ibmcloud.com/bpm/portal/rest/v1/UserProvisioningService.json
Basic Access Authentication over SSL
JSON
Account administrators only
HTTP GET
HTTP PUT
HTTP DELETE
Query Method – Listing users and retrieving user details
The user provisioning operation provides two forms of the query method. The base URI
behaves as a collection URI and will retrieve pages of user data from the subscription.
User data is limited to a maximum of 100 users per page. The second form, adding the
users e-mail address to the base URI, behaves as a element URI and retrieves the specific
details about the specific users account.
Collection URI: Listing all of the users for an account
Subject
Collection URI
URI Parameter
beginIndex
URI Parameter
endIndex
Response code HTTP
200
Response code HTTP
403
Response code HTTP
401
JSON response
beginIndex
JSON response
endIndex
JSON response
totalUsers
JSON response
nextPage
JSON response
previousPage
JSON response
users
Sample Request:
Sample Response
Details
https://<vhost>.bpm.ibmcloud.com/bpm/portal/rest/v1/UserProvisioningService.js
on[?beginIndex=<offsetA>[&endIndex=<offsetB>]]
The beginning offset to retrieve the user list from.
The end offset to retrieve the user list from. If the endIndex is greater than the
beginIndex + 100, the results will be limited to 100.
Query operation completed successfully
Access is forbidden. The specified credentials are invalid.
Access is forbidden. The specified credentials are not those of an administrator of
this account.
The beginIndex of the data retrieved
The endIndex of the data retrieved
The total number of users within the subscription
A URI to the next page of data, if there is a next page.
A URI to the previous page of data, if there is previous page
A JSON array of the user data beginning at beginEndex and ending at endIndex.
Each users data is formatted the same as the same as the element URI.
https://vhost00X.bpm.ibmcloud.com/bpm/portal/rest/v1/UserProvisioningService.
json?beginIndex=1&endIndex=2
{
"beginIndex": 1,
"endIndex": 2,
"nextPage": "
https:\/\/vhost00X.bpm.ibmcloud.com\/bpm\/portal\/rest\/v1\/UserProvisioningSer
vice.json?beginIndex=3&endIndex=3",
"previousPage": "
https:\/\/vhost00X.bpm.ibmcloud.com\/bpm\/portal\/rest\/v1\/UserProvisioningSer
vice.json?beginIndex=0&endIndex=0",
"totalUsers": 4,
"users": [
{
"accountAdmin": true,
"cn": "Richard",
"developer": true,
"endUser": false,
"mail": "[email protected]",
"operator": false,
"sn": "Duggan",
"tester": true
},
{
"accountAdmin": false,
"cn": "Pappa",
"developer": false,
"endUser": true,
"mail": "[email protected]",
"operator": false,
"sn": "Smurf",
"tester": false
}
]
}
Element URI: Retrieving the details of specific user.
Subject
Details
Element URI
https://<vhost>.bpm.ibmcloud.com/bpm/portal/rest/v1/UserProvisioningService.js
on/<email>
Query operation completed successfully
Response code HTTP
200
Response code HTTP
403
Response code HTTP
401
Response code HTTP
404
JSON response
accountAdmin
JSON response
cn
JSON response
developer
JSON response
endUser
JSON response
mail
JSON response
operator
JSON response
sn
JSON response
tester
Sample Request
Sample Response
Access is forbidden. The specified credentials are invalid.
Access is forbidden. The specified credentials are not those of an administrator of
this account.
The queried user is not a member of the subscription
Whether the queried user is an administrator of the subscription
The queried user’s first name
Whether the queried user has access to the Development Operating environment
Whether the queried user has access to the Process Runtime Operating
environment
The queried user’s e-mail address
Whether the queried user is an operator of the subscription. The user will be an
operator for any operating environment for which the user has access
The queried user’s last name
Whether the queried user has access to the Test Operating environment
https://vhost00X.bpm.ibmcloud.com/bpm/portal/rest/v1/UserProvisioningService.
json/[email protected]
{
"accountAdmin": true,
"cn": "Richard",
"developer": true,
"endUser": false,
"mail": "[email protected]",
"operator": false,
"sn": "Duggan",
"tester": true
}
Add Method – Provisioning Users
The user provisioning service provides a single form of the add method, therefore,
requiring that each user be added individually. There is no support for collections.
Provisioning Users
Subject
Details
Element URI
https://<vhost>.bpm.ibmcloud.com/bpm/portal/rest/v1/UserProvisioningService.
json
Add operation completed successfully
Response code HTTP
200
Response code HTTP
403
Response code HTTP
401
Response code HTTP
400
Response code HTTP
409
JSON request
cn
JSON request
developer
JSON request
endUser
JSON request
mail
JSON request
operator
JSON request
sn
JSON request
tester
Sample Request
Sample Response
Access is forbidden. The specified credentials are invalid.
Access is forbidden. The specified credentials are not those of an administrator
of this account.
Validation of the request data failed
User already exists
The user’s first name. Required
Whether the user will be granted access to the Development Operating
environment. Default false
Whether the user will be granted access to the Process Runtime Operating
environment. Default true
The user’s e-mail address. Required.
Whether the queried user will be granted the operator role for the subscription.
The user will be an operator for any operating environment for which the user
has access. Default false
The queried user’s last name. Required
Whether the user will be granted access to the Test Operating environment.
Default false
https://vhost00X.bpm.ibmcloud.com/bpm/portal/rest/v1/UserProvisioningServic
e.json
Delete Method – Archiving Users
The user deletion operation provides a single form of the delete method, therefore,
requiring that each user be deleted individually. There is no support for collections.
Subject
Details
Element URI
https://<vhost>.bpm.ibmcloud.com/bpm/portal/rest/v1/UserProvisioningServic
e.json/<email>
Delete operation completed successfully
Response code HTTP
200
Response code HTTP
403
Response code HTTP
401
Response code HTTP
404
Access is forbidden. The specified credentials are invalid.
Access is forbidden. The specified credentials are not those of an administrator
of this account.
The requested deleted user is not a member of the subscription