This content is dedicated to our next version. It is work in progress: its content will evolve until the new version is released. Before that time, it cannot be considered as official.

Identity API

The Identity Rest API allows to manage the Bonita’s organization.

Professional and Personal contact data

Description

Additional information about a user (personal and professional). Both resources have the same attributes.

Identifier

The user ID (a long value).

Representation

{
  "id":"user ID",
  "fax_number":"fax number",
  "building":"building",
  "phone_number":"phone number",
  "website":"website",
  "zipcode":"zipcode",
  "state":"state",
  "city":"city",
  "country":"country",
  "mobile_number":"mobile phone number",
  "address":"address",
  "room":"room",
  "email":"email"
}

Methods

The methods used for this resource are:

  • POST - Create a user’s contact information

  • GET - Read a user’s contact information

  • PUT - Update a user’s contact information

Create contact information

  • URL
    /API/identity/professionalcontactdata
    or
    /API/identity/personalcontactdata

  • Method
    POST

  • Request Payload
    A partial representation of a user’s contact information in JSON including the user ID (mandatory)

    {
      "id":"4",
      "fax_number":"484-302-0766",
      "building":"70",
      "phone_number":"484-302-5766",
      "zipcode":"19108",
      "state":"PA",
      "city":"Philadelphia",
      "country":"United States",
      "address":"Renwick Drive",
      "email":"walter.bates@acme.com"
    }
  • Success Response
    The full JSON representation of the user’s contact information that was created

    • Code: 200

    • Payload:

      {
        "id":"4",
        "fax_number":"484-302-0766",
        "building":"70",
        "phone_number":"484-302-5766",
        "website":"",
        "zipcode":"19108",
        "state":"PA",
        "city":"Philadelphia",
        "country":"United States",
        "mobile_number":"",
        "address":"Renwick Drive",
        "email":"walter.bates@acme.com",
        "room":""
      }
  • Error Response

    • Code: 403 if contact information for this user already exists

Read a user’s contact information

  • URL
    /API/identity/professionalcontactdata/:userId
    or
    /API/identity/personalcontactdata/:userId

  • Method
    GET

  • Success Response
    A user’s contact information in JSON

    • Code: 200

    • Payload:

      {
        "id":"4",
        "fax_number":"484-302-0766",
        "building":"70",
        "phone_number":"484-302-5766",
        "website":"",
        "zipcode":"19108",
        "state":"PA",
        "city":"Philadelphia",
        "country":"United States",
        "mobile_number":"",
        "address":"Renwick Drive",
        "email":"walter.bates@acme.com",
        "room":""
      }
  • Error Response

    • Code: 404 if no user with this ID is found

Update a user’s contact information

  • URL
    /API/identity/professionalcontactdata/:userId
    or
    /API/identity/personalcontactdata/:userId

  • Method
    PUT

  • Request Payload
    A partial representation of a user’s contact information in JSON with at least the mandatory "name" attribute

    {
      "fax_number":"484-302-0766",
      "building":"70",
      "phone_number":"484-302-5766",
      "zipcode":"19108",
      "state":"PA",
      "city":"Philadelphia",
      "country":"United States",
      "address":"Renwick Drive",
      "email":"walter.bates@acme.com"
    }
  • Error Response

    • Code: 404 if no user with this ID is found

Group

Description

The group a user belongs to. Groups have a hierarchy (subgroups can be created inside a group).

Identifier

The ID of the group (a long value).

Representation

{
  "id":"group ID",
  "name":"display name",
  "displayName":"name",
  "parent_path":"the path of the parent group of this group (empty if the group has no parent)",
  "path":"the full path of the group (including its parent path)",
  "description":"description",
  "creation_date":"creation date (format: "2014-12-31 15:17:24.736")",
  "created_by_user_id":"id of the user who created the group (-1 if the group was created by the tenant admin or by an organisation import)",
  "last_update_date":"last update date (format: "2014-12-31 15:17:24.736")",
  "icon":"icon path"
}

Methods

The methods used for this resource are:

  • POST - Create a group

  • GET - Read a group or search for a group

  • PUT - Update a group

  • DELETE - Remove a group

Create a group

  • URL
    /API/identity/group

  • Method
    POST

  • Data Params

  • Request Payload
    A partial representation of a group in JSON with at least the mandatory "name" attribute

    {
      "icon":"","name":"HR",
      "displayName":"Human Resources",
      "parent_group_id":"1",
      "description":"Human resources department"
    }
  • Success Response
    The full JSON representation of the group that was created

    • Code: 200

    • Payload:

      {
        "id":"14",
        "creation_date":"2014-12-02 16:19:28.925",
        "created_by_user_id":"4",
        "icon":"","parent_path":"/acme"
        ,"description":"Human resources department",
        "name":"HR",
        "path":"/acme/HR",
        "displayName":"Human Resources",
        "last_update_date":"2014-12-02 16:19:28.925"
      }
  • Error Response

    • Code: 403 if a group with the same name and parent already exists

Read a group

  • URL
    /API/identity/group/:groupId

  • Method
    GET

  • Success Response
    A group in JSON

    • Code: 200

    • Payload:

      {
        "id":"14",
        "creation_date":"2014-12-02 16:19:28.925",
        "created_by_user_id":"4",
        "icon":"","parent_path":"/acme",
        "description":"Human resources department",
        "name":"HR",
        "path":"/acme/HR",
        "displayName":"Human Resources",
        "last_update_date":"2014-12-02 16:19:28.925"
      }
  • Error Response

    • Code: 404 if no group with this ID is found

Search for a group

  • URL
    /API/identity/group
    Example: /API/identity/group?p=0&c=100&f=parent_path%3d/acme&d=parent_group_id&o=name%20ASC

  • Method
    GET

  • Data Params
    Standard search parameters are available to search form mappings.
    It is possible to filter on the following attributes:

    • name=<group_name>

    • displayName=<group_displayName>

    • parent\_path=<path_of_parent_group>

      It is possible to order by the value of the following attributes:

    • o=id ASC ou o=id DESC)

    • o=name ASC ou o=name DESC

    • o=displayName ASC ou o=displayName DESC

    It is also possible to retrieve the parent group ID.

    • d=<parent_group_id>

  • Success Response
    A list of groups in JSON

    • Code: 200

    • Payload:

      [
        {
          "id":"3",
          "creation_date":"2014-12-02 11:33:48.501",
          "created_by_user_id":"-1",
          "icon":"",
          "parent_path":"/acme",
          "description":"This group represents the finance department of the ACME organization",
          "name":"finance",
          "path":"/acme/finance",
          "parent_group_id":"1",
          "displayName":"Finance",
          "last_update_date":"2014-12-02 11:33:48.501"
        }, {
          "id":"14",
          "creation_date":"2014-12-02 16:19:28.925",
          "created_by_user_id":"4",
          "icon":"",
          "parent_path":"/acme",
          "description":"Human resources department",
          "name":"HR",
          "path":"/acme/HR",
          "parent_group_id":"1",
          "displayName":"Human Resources",
          "last_update_date":"2014-12-02 16:19:28.925"
        }
      ]

Update a group

  • URL
    /API/identity/group/:groupId

  • Method
    PUT

  • Request Payload
    A partial representation of a group in JSON with at least the mandatory "name" attribute

    {
      "name":"HR",
      "displayName":"Humman resources"
    }
  • Success Response
    The full JSON representation of the group that was updated

    • Code: 200

    • Payload:

      {
        "id":"14",
        "creation_date":"2014-12-02 16:19:28.925",
        "created_by_user_id":"4",
        "icon":"",
        "parent_path":"/acme",
        "description":"Human resources department",
        "name":"HR",
        "path":"/acme/HR",
        "displayName":"Human resources",
        "last_update_date":"2014-12-03 17:18:27.542"
      }
  • Error Response

    • Code: 403 if another group with the same name and parent already exists
      404 if no group with this ID is found

Delete a group

  • URL
    /API/identity/group/:groupId

  • Method
    DELETE

  • Success Response

    • Code: 200

  • Error Response

    • Code: 404 if no group with this ID is found

Membership

Description

Manage membership of users. There is a membership when a user belongs to a group and a role. Use this resource to add, search, and delete memberships.

Identifier

A compound identifier constructed from user_id/group_id/role_id where each id is a long value.

Representation

{
  "assigned_date":"creation date (format: "2014-12-31 15:17:24.736")",
  "role_id":"id of the role of this membership",
  "assigned_by_user_id":"id of the user who created the membership (-1 if the role was created by the tenant admin or by an organisation import)",
  "group_id":"id of the group of this membership",
  "user_id":"id of the user in this membership"
}

Methods

The methods used for this resource are:

  • POST - Create a membership

  • GET - Search for memberships of a user

  • DELETE - Remove a membership

  • DELETE - Remove a membership

Create a membership

This action creates (assigns) a membership to a user.

  • URL
    /API/identity/membership

  • Method
    POST

  • Request Payload
    A partial representation of a membership object with the mandatory "user_id", "group_id" and "role_id" attributes

    {
      "user_id":"4",
      "group_id":"5",
      "role_id":"1"
    }
  • Success Response
    The full JSON representation of the membership that was created

    • Code: 200

    • Payload:

      {
        "assigned_date":"2014-12-02 17:57:09.315",
        "role_id":"1",
        "assigned_by_user_id":"-1",
        "group_id":"5",
        "user_id":"4"
      }
  • Error Response

    • Code: 403 if a membership already exists

Search memberships of a user

This action search memberships of a user.

  • URL
    /API/identity/membership

  • Method
    GET

  • Data Params
    Standard search parameters are available.
    Required

    • filter is mandatory: user_id=<id of the user>

      It is possible to use the deploy option to retrieve the value of elements specified by an attribute value. For example, if you specify d=group_id, the result will contain the group details in place of the group id.

    • group d=group_id

    • role d=role_id

    • user d=user_id

    • user that created the membership d=assigned_by_user_id

      It is possible to order by the value of the following attributes:

    • o=ROLE_NAME_ASC or o=ROLE_NAME_DESC

    • o=GROUP_NAME_ASC or o=GROUP_NAME_DESC

    • o=ASSIGNED_DATE_ASC or o=ASSIGNED_DATE_DESC

    Example: Get the memberships for the user with id 125, and return the role details associated with each membership: /API/identity/membership?p=0&c=10&f=user\_id%3d125&d=role\_id

  • Success Response

    • Code: 200

    • Payload:

      [
        {
          "assigned_date":"2014-12-02 17:57:09.315",
          "role_id": {
            "creation_date":"2014-12-01 18:51:54.791",
            "created_by_user_id":"4",
            "id":"4",
            "icon":"",
            "description":"manager of the department",
            "name":"manager",
            "displayName":"department manager",
            "last_update_date":"2014-12-01 18:51:54.791"
          },
          "assigned_by_user_id":"12",
          "group_id":"5",
          "user_id":"125"
        }
      ]

Delete a membership

Delete a membership of a user using the group id and role id.

  • URL
    /API/identity/membership/:userId/:groupId/:roleId

  • Method
    DELETE

  • Success Response

    • Code: 200

Role

Description

The role of a user in a group

Identifier

The ID of the role (a long value).

Representation

{
  "id":"role ID",
  "name":"display name",
  "displayName":"name",
  "description":"description",
  "creation_date":"creation date (format: "2014-12-31 15:17:24.736")",
  "created_by_user_id":"Id of the user who created the role (-1 if the role was created by the tenant admin or by an organisation import)",
  "last_update_date":"last update date (format: "2014-12-31 15:17:24.736")",
  "icon":"icon path"
}

Methods

The methods used for this resource are:

  • POST - Create a role

  • GET - Read a role or search for a role

  • PUT - Update a role

  • DELETE - Remove a role

Create a role

  • URL
    /API/identity/role

  • Method
    POST

  • Request Payload
    A partial representation of a role in JSON with at least the mandatory "name" attribute

    {
      "icon":"",
      "name":"manager",
      "displayName":"department manager",
      "description":"manager of the department"
    }
  • Success Response
    The full JSON representation of the role that was created

    • Code: 200

    • Payload:

      {
        "creation_date":"2014-12-01 18:51:54.791",
        "created_by_user_id":"4",
        "id":"4",
        "icon":"",
        "description":"manager of the department",
        "name":"manager",
        "displayName":"department manager",
        "last_update_date":"2014-12-01 18:51:54.791"
      }
  • Error Response

    • Code: 403 if a role with the same name already exists

Read a role

  • URL
    /API/identity/role/:roleId

  • Method
    GET

  • Success Response
    A role in JSON

    • Code: 200

    • Payload:

      {
        "creation_date":"2014-12-01 15:17:24.736",
        "created_by_user_id":"-1",
        "id":"1",
        "icon":"",
        "description":"",
        "name":"member",
        "displayName":"Member",
        "last_update_date":"2014-12-01 15:17:24.736"
      }
  • Error Response

    • Code: 404 if no role with this ID is found

Search for a role

  • URL
    /API/identity/role
    Example: /API/identity/role?p=0&c=100&o=displayName ASC

  • Method
    GET

  • Data Params
    It is possible to filter on the following attributes

    • name=<role_name>

    • displayName=<role_displayName>

    It is possible to order by the value of the following attributes

    • id: o=id ASC or o=id DESC

    • name: o=name ASC or o=name DESC

    • displayName: o=displayName ASC or o=displayName DESC

  • Success Response
    A list of roles in JSON

    • Code: 200

    • Payload:

      [
        {
          "creation_date":"2014-12-01 18:51:54.791",
          "created_by_user_id":"4",
          "id":"4",
          "icon":"",
          "description":"manager of the department",
          "name":"manager",
          "displayName":"department manager",
          "last_update_date":"2014-12-01 18:51:54.791"
        },
        {
          "creation_date":"2014-12-01 15:17:24.736",
          "created_by_user_id":"-1",
          "id":"1",
          "icon":"",
          "description":"",
          "name":"member",
          "displayName":"Member",
          "last_update_date":"2014-12-01 15:17:24.736"
        }
      ]

Update a role

  • URL
    /API/identity/role/:roleId

  • Method
    PUT

  • Request Payload
    A partial representation of a role in JSON with at least the mandatory "name" attribute

    {
      "name":"Manager",
      "displayName":"Department manager"
    }
  • Success Response
    The full JSON representation of the role that was updated

    • Code: 200

    • Payload:

      {
        "creation_date":"2014-12-01 18:51:54.791",
        "created_by_user_id":"4",
        "id":"4",
        "icon":"",
        "description":"manager of the department",
        "name":"Manager",
        "displayName":"Department manager",
        "last_update_date":"2014-12-01 18:59:59.361"
      }
  • Error Response

    • Code: 403 : if a role with the same name already exists
      404 : if no role with this ID is found

Delete a role

  • URL
    /API/identity/role/:roleId

  • Method
    DELETE

  • Success Response

    • Code: 200

  • Error Response

    • Code: 404 if no role with this ID is found

User

Description

Used to manage information about users.

Representation

Returns a JSON representation of user details. The "manager_id" and "professional_data" are omitted unless they are requested in the payload.

{
  "last_connection":"date",
  "created_by_user_id":"number",
  "creation_date":"date",
  "id":"number",
  "icon":"string",
  "enabled":"true | false",
  "title":"string",
  "professional_data": {
    "fax_number":"string",
    "building":"string",
    "phone_number":"string",
    "website":"string",
    "zipcode":"string",
    "state":"string",
    "city":"string",
    "country":"string",
    "id":"number",
    "mobile_number":"string",
    "address":"string",
    "email":"string",
    "room":"string"
  },
  "manager_id":{
    "last_connection":"date",
    "created_by_user_id":"number",
    "creation_date":"date",
    "id":"number",
    "icon":"string",
    "enabled":"true | false",
    "title":"string",
    "manager_id":"number",
    "job_title":"string",
    "userName":"string",
    "lastname":"string",
    "firstname":"string",
    "password":"",
    "last_update_date":"date"
  },
  "job_title":"string",
  "userName":"string",
  "lastname":"string",
  "firstname":"string",
  "password":"",
  "last_update_date":"date"
}

Methods

The methods used for this resource are:

  • POST - Create a user

  • GET - Read a user details or search for a group of users

  • PUT - Update a user

  • DELETE - Remove a user

Create a user

  • URL
    /API/identity/user

  • Method
    POST

  • Request Payload
    A partial representation of a user in JSON

    {
      "userName":"New.User",
      "password":"bpm",
      "password_confirm":"bpm",
      "icon":"",
      "firstname":"New",
      "lastname":"User",
      "title":"Mr",
      "job_title":"Human resources benefits",
      "manager_id":"3"
    }
  • Success Response
    The full JSON representation of the user that was created
    After creation, the user is in inactive state.

    • Code: 200

    • Payload:

      {
        "last_connection":"",
        "created_by_user_id":"4",
        "creation_date":"2014-12-09 17:43:28.291",
        "id":"101",
        "icon":"/default/icon_user.png",
        "enabled":"false",
        "title":"Mr",
        "manager_id":"3",
        "job_title":"Human resources benefits",
        "userName":"New.User",
        "lastname":"New",
        "firstname":"User",
        "password":"",
        "last_update_date":"2014-12-09 17:43:28.291"
      }

Read a user details

  • URL
    /API/identity/user/:userId
    Example: Get details of a specified user including professional and manager information : /API/identity/user/21?d=professional\_data&d=manager\_id

  • Method
    GET

  • Data Params
    Standard search parameters are available.

    • d=professional_data - include professionnal data in response

    • d=manager_id - include details of user’s manager in response

  • Success Response
    The full JSON representation of the user

    • Code: 200

    • Payload:

      {
        "last_connection":"",
        "created_by_user_id":"-1",
        "creation_date":"2014-12-01 10:39:55.177",
        "id":"21",
        "icon":"/default/icon_user.png",
        "enabled":"true",
        "title":"Mrs",
        "professional_data":{
          "fax_number":"484-302-0430",
          "building":"70",
          "phone_number":"484-302-5430",
          "website":"",
          "zipcode":"19108",
          "state":"PA",
          "city":"Philadelphia",
          "country":"United States",
          "id":"21",
          "mobile_number":"",
          "address":"Renwick Drive",
          "email":"giovanna.almeida@acme.com",
          "room":""
        },
        "manager_id":{
          "last_connection":"",
          "created_by_user_id":"-1",
          "creation_date":"2014-12-01 10:39:55.136",
          "id":"17",
          "icon":"/default/icon_user.png",
          "enabled":"true",
          "title":"Mrs",
          "manager_id":"1",
          "job_title":"Vice President of Sales",
          "userName":"daniela.angelo",
          "lastname":"Angelo",
          "firstname":"Daniela",
          "password":"",
          "last_update_date":"2014-12-01 10:39:55.136"
        },
        "job_title":"Account manager",
        "userName":"giovanna.almeida",
        "lastname":"Almeida",
        "firstname":"Giovanna",
        "password":"",
        "last_update_date":"2014-12-01 10:39:55.177"
      }

Search for a group of users

  • URL
    /API/identity/user
    Example: Search for users with names that contain "will", filter to keep only enabled users, and order the result by last name.: /API/identity/user?p=0&c=10&o=lastname%20ASC&s=will&f=enabled%3dtrue

  • Method
    GET

  • Data Params
    Standard search parameters are available.

    • `d=professional_data - include professionnal data in response

    • `d=manager_id - include details of user’s manager in response

  • Success Response
    A JSON array of users

    • Code: 200

    • Payload:

      [
        {
          "last_connection":"2014-12-09 14:52:06.092",
          "created_by_user_id":"-1",
          "creation_date":"2014-12-08 17:16:40.984",
          "id":"1","icon":"/default/icon_user.png",
          "enabled":"true",
          "title":"Mr",
          "manager_id":"0",
          "job_title":"Chief Executive Officer",
          "userName":"william.jobs",
          "lastname":"Jobs",
          "firstname":"William",
          "password":"",
          "last_update_date":"2014-12-08 17:16:40.984"
        },
        {
          "last_connection":"",
          "created_by_user_id":"-1",
          "creation_date":"2014-12-08 17:16:41.030",
          "id":"5",
          "icon":"/default/icon_user.png",
          "enabled":"true",
          "title":"Mr",
          "manager_id":"1",
          "job_title":"Chief Financial Officer",
          "userName":"zachary.williamson",
          "lastname":"Williamson",
          "firstname":"Zachary",
          "password":"",
          "last_update_date":"2014-12-08 17:16:41.030"
        }
      ]

Update a user

  • URL
    API/identity/user/:userId

  • Method
    PUT

  • Request Payload
    A JSON representation of the user, with the new information.
    Example: Update user details including professional and manager information: /API/identity/user/4

    {
      "id"="4",
      "userName":"walter.bates",
      "password":"bpm",
      "password_confirm":"bpm",
      "icon":"",
      "firstname":"Walter",
      "lastname":"Bates",
      "title":"Mr",
      "job_title":"Human resources benefits",
      "manager_id":"3"
    }

    Deactivate the user identified by id 9 : /API/identity/user/9

    {
      "enabled":"false"
    }
  • Success Response

    • Code: 200

Remove a user

Use this method with caution: some artifacts like applications, cases or users may present display problems in the Bonita Applications if the referenced user was deleted.
Note that you can disable a user instead of deleting it. To do so, use the UPDATE method and set the attribute 'enabled' to false

  • URL
    /API/identity/user/:userId

  • Method
    DELETE

  • Success Response

    • Code: 200