How to use Bonita BPM 6 Web REST API in Python: create accounts

jeremy.jacquier-roux's picture
jeremy.jacquier-roux
Blog Categories: 

This tutorial shows how to use the web REST API provided by Bonita BPM 6 in order to create new accounts in Python. You need to have a working Bonita BPM 6 to test the code below. This can be done with Bonita BPM Studio after deploying Bonita BPM Portal.
This example is run on a Linux distribution (Ubuntu 12.04 LTS).
The official documentation is available here http://documentation.bonitasoft.com/web-rest-api
Note: I'm not a Python developer and there are always many ways to accomplish the same thing. Don't hesitate to improve this example!

Useful modules

The following Python modules will be helpful:

  • argparse
  • httplib2
  • json
  • urllib

Authentication

Before going further, log in and retrieve the corresponding cookie. You can do it this way:

  1. def portal_login(url,username,password,disable_cert_validation):<br />
  2. http = httplib2.Http(disable_ssl_certificate_validation=disable_cert_validation)<br />
  3. API="/loginservice"<br />
  4. URL=url+API<br />
  5. body={'username': username, 'password': password, 'redirect': 'false'}<br />
  6. headers={"Content-type":"application/x-www-form-urlencoded"}<br />
  7. response, content = http.request(URL,'POST',headers=headers,body=urllib.urlencode(body))<br />
  8. if response.status!=200:<br />
  9. raise Exception("HTTP STATUS: "+str(response.status))<br />
  10. return response['set-cookie']

If you run the Bonita BPM Portal from Studio, you can use these parameters:

disable_cert_validation should be set to false by default. It's useful only for test purposes, when we use a self-signed certificate.

Create a user

Use the following function to create a user using the previous cookie:

  1. def create_user(url,cookie,username,password,firstname,lastname,disable_cert_validation):<br />
  2. http = httplib2.Http(disable_ssl_certificate_validation=disable_cert_validation)<br />
  3. API="/API/identity/user/"<br />
  4. URL=url+API<br />
  5. headers={"Content-type":"application/json",'Cookie': cookie}<br />
  6. data={"userName":username,"password":password,"firstname":firstname,"lastname":lastname, "enabled": "true"}<br />
  7. data = json.dumps(data)<br />
  8. response, content = http.request(URL, 'POST',headers=headers, body=data)<br />
  9. if response.status!=200:<br />
  10. raise Exception("HTTP STATUS: "+str(response.status)+" "+content)<br />
  11. else:<br />
  12. data = json.loads(content)<br />
  13. return data['id']

Add a user to a profile

Retrieve a profile id

This function return the profile id, this way we can search for both Administrator and User profile:

  1. def get_profile_id(url,cookie,name,disable_cert_validation):<br />
  2. http = httplib2.Http(disable_ssl_certificate_validation=disable_cert_validation)<br />
  3. API="/API/userXP/profile"<br />
  4. params="?f=name="+str(name)<br />
  5. URL=url+API+params<br />
  6. headers={"Content-type":"application/x-www-form-urlencoded",'Cookie': cookie}<br />
  7. response, content = http.request(URL, 'GET',headers=headers)<br />
  8. data = json.loads(content)<br />
  9. try:<br />
  10. return data[0]['id']<br />
  11. except Exception, e:<br />
  12. return None

Link the user to a profile

This last function permits to link the user previously created using its id and the profile id retrieved before:

  1. def add_user_to_profile(url,cookie,uid,pid,disable_cert_validation):<br />
  2. http = httplib2.Http(disable_ssl_certificate_validation=disable_cert_validation)<br />
  3. API="/API/userXP/profileMember/"<br />
  4. URL=url+API<br />
  5. headers={"Content-type":"application/json",'Cookie': cookie}<br />
  6. data={"profile_id":pid,"member_type":"USER","user_id": uid}<br />
  7. data = json.dumps(data)<br />
  8. response, content = http.request(URL, 'POST',headers=headers, body=data)<br />
  9. if response.status!=200:<br />
  10. raise Exception("HTTP STATUS: "+str(response.status)+" "+content)

Full example

You can download a full example here: create_bonita_account.py

  1. usage: create_bonita_account.py --login install --password install --url<br />
  2. http://example.com:8080/bonita --new_login<br />
  3. john.smith --new_password mysecret --firstname<br />
  4. John --lastname Smith [-h]<br />
  5. [--disable_ssl_certificate_validation]<br />
  6. [--is_admin]<br />
  7. <br />
  8. Create a Bonita account<br />
  9. <br />
  10. required arguments:<br />
  11. --login install Account used to authenticate you on Bonita<br />
  12. --password install Password used with your account<br />
  13. --url http://example.com:8080/bonita<br />
  14. Bonita BPM url<br />
  15. --new_login john.smith<br />
  16. New account that will be created<br />
  17. --new_password mysecret<br />
  18. Password used for the new account<br />
  19. --firstname John First name used for the new account<br />
  20. --lastname Smith Last name used for the new account<br />
  21. <br />
  22. optional arguments:<br />
  23. -h, --help Show this help message and exit<br />
  24. --disable_ssl_certificate_validation<br />
  25. Used this only for tests with a self-signed<br />
  26. certificate<br />
  27. --is_admin Assign user to Administrator profile

To create a new account with the Administrator profile, you can launch a command like:

./create_bonita_account.py --login walter.bates --password bpm --url http://localhost:8080/bonita --new_login john.smith --new_password pass --firstname John --lastname Smith --is_admin

If you use an url in https with a self-signed certificate, it may raise this error:

httplib2.SSLHandshakeError: [Errno 1] _ssl.c:504: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

You can avoid this verification (for test only!) using the parameter "--disable_ssl_certificate_validation".

Comments

Submitted by aCordier on Thu, 01/09/2014 - 14:38

Hello and thank you,

How can we now how to properly construct the json representation for any operation we want to execute on a resource using rest API. Is there a documentation pointing to this ?

EDIT: there's no need for such a documentation, it works just fine :)

Antoine

Submitted by simon.tilbrook on Sat, 04/05/2014 - 20:47

When I use the REST API to create users they are inactive until they are manually activated via the Portal. Is there any way to create new users with enabled=true using the REST API?

Submitted by simon.tilbrook on Sat, 04/05/2014 - 21:24

In fact I've found the answer myself - enabled must be set to the string value "true", e.g.: {"enabled":"true","title":"Mr","password_confirm":"......","job_title":"ADV","lastname":"Last","userName":"USER-03","firstname":"First","password":"......"}

Submitted by simon.tilbrook on Sun, 04/06/2014 - 15:02

I now have working code to create active users and add them as members of roles/groups using the REST API. I cannot however populate the professionalcontactinfo fields using a POST - I always get an HTTP 500 error. Does anyone have a working example of the JSON to pass to update the user_contactinfo table?

In case it helps, the message I've tried to send looks like this:

Sending {"phone_number":"\+9999999999","address":"99 Xxxxxxxxxxxxxxxx, Xxxxxxx","email":"xxxxxxxxxx@xxxxxxxx.com","city":"London","country":"United Kingdom"} to URL : http://server:8080/bonita/API/identity/professionalcontactdata/999

And the error I get looks like this

{"exception":"class java.lang.NullPointerException","message":"","stacktrace":[" org.bonitasoft.web.toolkit.client.common.json.JSonItemReader.parseItem(JSonItemR eader.java:212)","org.bonitasoft.web.toolkit.client.common.json.JSonItemReader.p arseItem(JSonItemReader.java:198)","org.bonitasoft.web.toolkit.client.common.jso n.JSonItemReader.parseItem(JSonItemReader.java:188)","org.bonitasoft.web.toolkit .client.common.json.JSonItemReader.parseItem(JSonItemReader.java:168)","org.boni tasoft.web.rest.server.framework.APIServletCall.getJSonStreamAsItem(APIServletCa ll.java:84)"

Submitted by simon.tilbrook on Tue, 04/08/2014 - 11:04

in case it helps others, I found the solution to this myself too. As the user already exists, a PUT must be used to add the contact details, not a POST.

Testing
Notifications