RESTful User Provisioning with IBM Business Process Manager on Cloud

Transcription

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

2 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 URL Endpoint Authentication Data Mime type Access restrictions Query Method Add Method Delete method Basic Access Authentication over SSL JSON Account administrators only HTTP GET HTTP PUT HTTP DELETE

3 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 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 Collection URI on[?beginindex=<offseta>[&endindex=<offsetb>]] URI Parameter The beginning offset to retrieve the user list from. beginindex URI Parameter The end offset to retrieve the user list from. If the endindex is greater than the endindex 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 beginindex The endindex of the data retrieved endindex The total number of users within the subscription totalusers A URI to the next page of data, if there is a next page. nextpage A URI to the previous page of data, if there is previous page previouspage A JSON array of the user data beginning at beginendex and ending at endindex. users Each users data is formatted the same as the same as the element URI. Sample Request: json?beginindex=1&endindex=2 Sample Response { "beginindex": 1, "endindex": 2, "nextpage": " vice.json?beginindex=3&endindex=3", "previouspage": " vice.json?beginindex=0&endindex=0", "totalusers": 4, "users": [ { "accountadmin": true, "cn": "Richard", "developer": true, "enduser": false, "mail": "rduggan@ca.ibm.com",

4 "operator": false, "sn": "Duggan", "tester": true }, { "accountadmin": false, "cn": "Pappa", "developer": false, "enduser": true, "mail": "psmurf@example.com", "operator": false, "sn": "Smurf", "tester": false } ] } Element URI: Retrieving the details of specific user. Element URI 404 accountadmin cn developer enduser mail operator sn tester Sample Request Sample Response { on/< > 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 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 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 json/rduggan@ca.ibm.com "accountadmin": true, "cn": "Richard", "developer": true, "enduser": false,

5 "mail": "operator": false, "sn": "Duggan", "tester": true }

6 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 Element URI cn developer enduser mail operator sn tester Sample Request Sample Response json Add 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. 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 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 e.json

7 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. Element URI e.json/< > Delete 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 requested deleted user is not a member of the subscription