Portal API

Portal API in Bonita is used to access and manage the following resources: Page, Profile, ProfileMember

Page

Description

Use the page resource to access custom pages, UI Designer pages, layouts or forms and REST API extensions.

Identifier

Simple, the ID of the object (a long value)

Representation

{
    "id":"_page_id_",
    "creationDate":"_date and time_",
    "createdBy":"_created_by_user_id_",
    "isProvided":"_true|false_",
    "description":"_description_",
    "contentName":"_custom_page_name_",
    "displayName":"_custom_page_display_name_",
    "updatedBy":"_updatedBy_user_id_",
    "lastUpdateDate":"_date_and_time_",
    "urlToken":"_custom_page_urlToken_"
}

Methods

The methods used for this resource are:

  • POST - Add a new custom page

  • GET - Read or search a custom page

  • PUT - Update a custom page

  • DELETE - Remove a custom page

Retrieve a Custom Page

Use a GET method to retrieve information about a custom page.

  • URL
    /API/portal/page/:pageId

  • Method
    GET

  • Success Response

    • Code: 200

    • Payload:

      {
  "id":"1",
  "creationDate":"2014-12-02 15:54:45.249",
  "createdBy":"",
  "isProvided":"true",
  "description":"HTML and Javascript example of custom page source structure (in English).",
  "contentName":"bonita-html-page-example.zip",
  "displayName":"HTML example page",
  "updatedBy":"-1",
  "lastUpdateDate":"2014-12-02 15:54:45.249",
  "urlToken":"custompage_htmlexample"
}

Add a new custom page

Use the POST method to create a new custom page. To add a new custom page, there are two steps:

  1. Upload the page content using the pageUpload servlet. This returns a temporary file name.

  2. Call this API with the temporary file name, as in the example below.

    • URL
      /API/portal/page Example: Add the custom page that was given the temporary name tmp_2181700538398444744.zip. The original name was bonita-angular-dashboard.zip.

    • Method
      POST

    • Request Payload

      {
  "pageZip":"tmp_113096560980259488.zip:bonita-angular-dashboard.zip"
}

    • Success Response

      • Code: 200

      • Payload:

        {
  "id":"103",
  "creationDate":"2014-12-04 14:54:06.967",
  "createdBy":"1",
  "isProvided":"false",
  "description":"AngularJS dashboard using ngBonita",
  "contentName":"bonita-angular-dashboard.zip",
  "displayName":"AngularJS dashboard",
  "updatedBy":"1",
  "lastUpdateDate":"2014-12-04 14:54:06.967",
  "urlToken":"custompage_angulardashboard"
}

Update a custom page

Use the PUT method to update an existing custom page. To update a custom page, upload the new page content using the pageUpload servlet, which returns a temporary file name, and then call this API with the temporary file name.

  • URL
    /API/portal/page/:pageId
    Example: Update the custom page with id = 103. The new uploaded file was given the temporary name tmp_4338264789005487499.zip. The original name was new-bonita-angular-dashboard.zip.

  • Method
    PUT

  • Request Payload

    {
  "pageZip":"tmp_4338264789005487499.zip:new-bonita-angular-dashboard.zip"
}

  • Success Response

    • Code: 200

Search custom pages

Use a GET method with filters and search terms to search for custom pages.

  • URL
    /API/portal/page?p={page}&c={count}&o={orders}&f={filters}&s={search}&d={deploy}

  • Method
    GET

  • Data Params
    Standard search parameters are available.
    You can filter on:

    • createdBy={user_id}: retrieve only the pages created by the specified user ID. For example, to retrieve the custom pages created by the user with id 1: http://localhost:8080/bonita/API/portal/page?p=0&c=10&f=createdBy%3d1.

    • contentType={contentType}: retrieve only the resources of requested type. This filter is available since v7.0. For example, to retrieve the theme resources: http://localhost:8080/bonita/API/portal/page?p=0&c=10&f=contentType%3Dtheme.

    You can search on:

    • displayName or description: search for custom pages with a displayName or description that starts with the specified string. For example, to find the pages with displayName starting with New: http://localhost:8080/bonita/API/portal/page?p=0&c=10&s=New

  • Success Response
    An array of custom page objects

    • Code: 200

Delete a custom page

Use the DELETE method to delete an existing custom page

  • URL
    /API/portal/page/:pageId

  • Method
    DELETE

  • Success Response

    • Code: 200

Profile

Description

Use the profile resource to access profiles.

Identifier

Simple, the ID of the object (a long value)

Representation

    {
    "id":"_profile id_",
    "creationDate":"_date and time of profile creation_",
    "icon":"_icon used in the Bonita Applications to represent the profile_",
    "createdBy":"_id of the uer who created the profile_",
    "description":"_a description of the profile_",
    "name":"_profile name_",
    "is_default":"_true | false _",
    "lastUpdateDate":"_date and time of the last update to the profile_",
    "updatedBy":"_the id of the user who last updated the profile_"
    }

Methods

The methods used for this resource are:

  • POST - Add a new profile

  • GET - Read or search a profile

  • PUT - Update a profile

  • DELETE - Remove a profile

Retrieve a Profile

Use a GET method to retrieve information about a profile.

  • URL
    /API/portal/profile/:profileId

  • Method
    GET

  • Success Response

    • Code: 200

    • Payload:

      {
  "id":"1",
  "creationDate":"2014-12-02 15:54:44.395",
  "icon":"/profiles/profileUser.png",
  "createdBy":"-1",
  "description":"The user can view and perform tasks and can start a new case of a process.",
  "name":"User",
  "is_default":"true",
  "lastUpdateDate":"2014-12-04 11:05:14.490",
  "updatedBy":"1"
}

Add a new profile

Use the POST method to create a new profile.

  • URL
    /API/portal/profile

  • Method
    POST

  • Request Payload

      {
    "name":"MyCustomProfile",
    "description":"This is my custom profile"
  }

  • Success Response

    • Code: 200

    • Payload:

      {
  "id":"101",
  "creationDate":"2014-12-04 16:29:23.434",
  "icon":"/profiles/profileDefault.png",
  "createdBy":"1",
  "description":"This is my custom profile",
  "name":"MyCustomProfile",
  "is_default":"false",
  "lastUpdateDate":"2014-12-04 16:29:23.434",
  "updatedBy":"1"
}

Update a profile

Use the PUT method to update an existing profile.

  • URL
    /API/portal/profile/:profileId

  • Method
    PUT

  • Request Payload

    {
  "id":"101",
  "name":"MyUpdatedCustomProfile",
  "description":"This is my updated custom profile"
}

  • Success Response

    • Code: 200

Search profiles

Use a GET method with filters and search terms to search for profiles.

  • URL
    /API/portal/profile?p={page}&c={count}&o={orders}&f={filters}&s={search}&d={deploy}

  • Method
    GET

  • Data Params
    Standard search parameters are available.
    You can filter on:

    • name={exact_profile_name}: retrieve only the profiles with the specified name. For example, retrieve the profile with name=Administrator: /API/portal/profile?p=0&c=10&f=name%3dAdministrator

    • hasNavigation={true|false}: retrieve the profiles with (or without) attached navigation pages (profile entries): /API/portal/profile?p=0&c=10&f=hasNavigation=true

    You can search on:

    • name: search all profiles which name starts with the search string. For example, name starting with Adm: /API/portal/profile?p=0&c=10&s=Adm

  • Success Response

    • Code: 200

    • Payload:
      An array of profile objects

Delete a profile

Use the DELETE method to delete an existing profile

  • URL
    /API/portal/profile/

  • Method
    DELETE

  • Success Response

    • Code: 200

ProfileMember

Description

A profileMember represents the association between the organization and profiles. In an organization we have three member_types = USER, GROUP and ROLE. You can assign a profile to a user by specifying a role, group, or specific user.

Identifier

Simple, the ID of the object (a long value)

Representation

{
  "id":"_profileMemberid_",
  "profile_id":"_id of the profile for this mapping_",
  "role_id":"_id of role, or -1 if the member type is not role_",
  "group_id":"_id of group, or -1 if the member type is not group_",
  "user_id":"_id of user, or -1 if the member type is not user_"
}

Methods

The methods used for this resource are:

  • POST - Add a new profileMember

  • GET - Search a profileMember

  • DELETE - Remove a profileMember

Add a new profileMember

Use the POST method to create a new profileMember.

  • URL
    API/portal/profileMember

  • Method
    POST

  • Request Payload
    Example 1: Add a member_type = USER to the profile with id = 2.

    {
  "profile_id":"2",
  "member_type":"USER",
  "user_id":"101"
}

    Example 2: Add a member_type = GROUP to the profile with id = 2.

    {
  "profile_id":"2",
  "member_type":"GROUP",
  "group_id":"8"
}

  • Success Response

    • Code: 200

    • Payload:
      Example 1 response ;

      {
  "id":"204",
  "profile_id":"2",
  "role_id":"-1",
  "group_id":"-1",
  "user_id":"101"
}

      Example 2 response ;

      {
  "id":"206",
  "profile_id":"2",
  "role_id":"-1",
  "group_id":"8",
  "user_id":"-1"
}

Search profileMembers

Use a GET method with filters and search terms to search for profileMembers.

  • URL
    /API/portal/profileMember?p={page}&c={count}&o={orders}&f={filters}&d={deploy}

  • Method
    GET

  • Data Params
    Standard search parameters are available.
    There is a mandatory filter on:

    • member_type=. For example, retrieve the profileMembers of type user: /API/portal/profileMember?p=0&c=10&f=member_type%3duser

    You can also filter also on:

    • profile_id={profile_id}: retrieve only the profileMembers related to the specified profile_id. /API/portal/profileMember?p=0&c=10&f=member_type%3duser&f=profile_id%3d1

    • user_id={user_id}: retrieve only the profileMembers related to the specified user_id. API/portal/profileMember?p=0&c=10&f=member_type%3duser&f=profile_id%3d1&f=user_id%3d101

    • role_id={role_id}: retrieve only the profileMembers related to the specified role_id. API/portal/profileMember?p=0&c=10&f=member_type%3drole&f=profile_id%3d1&f=role_id%3d101

    • group_id={group_id}: retrieve only the profileMembers related to the specified group_id. API/portal/profileMember?p=0&c=10&f=member_type%3dgroup&f=profile_id%3d1&f=group_id%3d101

  • Success Response
    An array of profileMember objects

    • Code: 200

Delete a profileMember

Use the DELETE method to delete an existing profileMember.

  • URL
    /API/portal/profileMember/:profileMemberId

  • Method
    DELETE

  • Success Response

    • Code: 200