Skip to content

Create tenant with roles, groups and users

In this example we will use REST API to create new tenant account with its roles, groups, extensions and users.

We will use cURL utility to send REST API requests to MiaRec server.

Prerequisites:

  • User account should be created in MiaRec web portal for REST API application. This account should have appropriate role permissions to access and modify MiaRec data. In this example, we use account with login apiuser and password secret. Its role is Administrator will full access to system. The user account should belong to "System" tenant otherwise it will not be able to create tenants.

In this example we will create:

  • Tenant account with name 'Acme Tenant'
  • Two groups within this tenant with names 'Agents Group' and 'Managers Group'
  • Two user roles with names 'Agent Role' and 'Manager Role'
  • A few users inside both of groups and with both of roles

Step 1. Verify REST API connection

Execute the following CURL command to retrieve a list of tenants:

curl -u apiuser:secret http://{host}:{port}/api/v2/tenants.json

Expected result is something like the following. If you see any error instead, then check your REST API user role permissions.

{
  "next_url": null,
  "total": 8,
  "tenants": [
    {
      "tenant_id": "34c7f1f6-9201-11e5-a739-e03f497dbdff",
      "timezone": null,
      "name": "Flexus",
      "encrypt_data": false,
      "fieldset_associate_calls": {
        "extension_uniquness": "systemwide",
        "associate_calls": "broadworks_group",
        "broadworks_sp_id": "FlexusProvider",
        "broadworks_group_id": "FlexusGroup",
        "associate_calls_condition": "BroadWorks-serviceProviderID = \"FlexusProvider\" AND BroadWorks-groupID = \"FlexusGroup\"",
        "cisco_partition": "",
        "metaswitch_system": "",
        "metaswitch_group": "",
        "sip_uri_host": "",
        "record_unknown_users": "record",
        "auto_provision": true,
        "provision_role_id": "34cafffe-9201-11e5-b516-e03f497dbdff",
        "provision_group_id": "47f53fcc-9201-11e5-b4ef-e03f497dbdff"
      },
      "fieldset_licensing": {
        "recording_seats": 20,
        "evaluation_seats": 20,
        "recording_sessions": 0,
        "monitoring_seats": 10,
        "license_mode": "fixed",
        "monitoring_sessions": null
      }
    },
    ... MORE DATA ...
}

Step 2. Create tenant account

To create new record we need to submit HTTP POST request with JSON tenant data.

Prepare JSON tenant data in a temporary file with name add_tenant.json. Content of this file:

{
  "tenant": {
      "name": "Acme Tenant",
      "encrypt_data": false,
      "fieldset_licensing": {
        "license_mode": "fixed",
        "recording_seats": 50,
        "evaluation_seats": 50
      }
    }
}

If any tenant configuration parameter is not provided in the submitted JSON data, then a default value will be used. For example, we skipped such parameter like "timezone".

Execute CURL command to add this tenant:

curl -u apiuser:secret -H "Content-Type: application/json" -X POST --data "@add_tenant.json" http://{host}:{port}/api/v2/tenants.json

If the tenant account is created successfully, then URL to new tenant's profile page is returned in the response message:

{"url": "/api/v2/tenants/00416392-cf76-11e5-a728-e03f497dbdff.json"}

Now we can retrieve tenant's data with HTTP GET request:

curl -u apiuser:secret http://{host}:{port}/api/v2/tenants/00416392-cf76-11e5-a728-e03f497dbdff.json

Step 3. Create user roles

We will create two roles:

  • Group Manager Role
  • Agent Role

Prepare JSON data in temporary files for each of roles.

Make sure that "tenant_id" is set to the ID for newly created tenant from the previous step. In our example it is 00416392-cf76-11e5-a728-e03f497dbdff.

Content of file add_role_manager.json:

{
  "role": {
    "name": "Group Manager Role",
    "access_level": "managed_groups",
    "tenant_id": "00416392-cf76-11e5-a728-e03f497dbdff",
    "permissions": {
      "calls": [
        "categorize",
        "playback",
        "pause_recording",
        "live_monitor",
        "view",
        "on_demand_trigger",
        "add_notes"
      ],
      "call_categories": [
        "view",
        "delete",
        "edit"
      ],
      "call_notes_own": [
        "view",
        "pin",
        "delete"
      ],
      "call_notes": [
        "view",
        "pin"
      ]
    }
  }
}

Content of file add_role_agent.json:

{
  "role": {
    "name": "Agent Role",
    "access_level": "user",
    "tenant_id": "00416392-cf76-11e5-a728-e03f497dbdff",
    "permissions": {
      "calls_own": [
        "view",
        "categorize",
        "playback",
        "pause_recording",
        "on_demand_trigger",
        "add_notes"
      ],
      "call_categories": [
        "view",
        "delete",
        "edit"
      ],
      "call_notes_own": [
        "view",
        "pin",
        "delete"
      ],
      "call_notes": [
        "view",
        "pin"
      ]
    }
  }
}

Execute CURL command to add "Group Manager Role" role:

curl -u apiuser:secret -H "Content-Type: application/json" -X POST --data "@add_role_manager.json" http://{host}:{port}/api/v2/roles.json

If role is created successfully, then the response message contains URL to new role's data:

{"url": "/api/v2/roles/e4195b2c-cf78-11e5-9367-e03f497dbdff.json"}

Repeat the same steps for role "Agent Role":

curl -u apiuser:secret -H "Content-Type: application/json" -X POST --data "@add_role_agent.json" http://{host}:{port}/api/v2/roles.json

Success response:

{"url": "/api/v2/roles/14e1c064-cf79-11e5-9804-e03f497dbdff.json"}

Step 4. Create user groups

We will create two groups:

  • Managers Group
  • Agents Group

Prepare JSON data in temporary files for each of groups.

Make sure that "tenant_id" is set to the ID for newly created tenant from the previous step. In our example it is 00416392-cf76-11e5-a728-e03f497dbdff.

Content of file add_group_managers.json:

{
  "group": {
    "tenant_id": "00416392-cf76-11e5-a728-e03f497dbdff",
    "name": "Managers Group"
  }
}

Content of file add_group_agents.json:

{
  "group": {
    "tenant_id": "00416392-cf76-11e5-a728-e03f497dbdff",
    "name": "Agents Group"
  }
}

CURL command for adding group "Managers Group":

curl -u apiuser:secret -H "Content-Type: application/json" -X POST --data "@add_group_managers.json" http://{host}:{port}/api/v2/groups.json

If group is created successfully, then the response message contains URL to group's data:

{"url": "/api/v2/groups/5fce93a8-cf7a-11e5-8e94-e03f497dbdff.json"}

Repeat the same steps for group "Agents Group":

curl -u apiuser:secret -H "Content-Type: application/json" -X POST --data "@add_group_agents.json" http://{host}:{port}/api/v2/groups.json

Success response:

{"url": "/api/v2/groups/7248c8f0-cf7a-11e5-adb9-e03f497dbdff.json"}

Step 5. Create user accounts

We will create two users:

  • Peter has role "Group Manager Role" and he belongs to group "Managers". Peter is also a manager of group "Agents".
  • David has role "Agent Role" and he belongs to group "Agents".

Prepare JSON data file add_user_peter.json with the following content:

{
    "user": {
        "name": "Peter",
        "is_active": true,
        "role_id": "e4195b2c-cf78-11e5-9367-e03f497dbdff",
        "group_id": "5fce93a8-cf7a-11e5-8e94-e03f497dbdff",
        "managed_groups": [
            "7248c8f0-cf7a-11e5-adb9-e03f497dbdff"
        ],
        "timezone": "Europe/London",
        "fieldset_login": {
            "can_login": true,
            "login": "peter",
            "password": "secret",
            "authenticate_type": "password"
        },
        "fieldset_recording": {
            "extensions": ["2001", "2002"],
            "record": "always",
            "record_direction": ["in", "out"]
        },
        "fieldset_licensing":
        {
            "recording_seat": true
        }
    }
}

Replace in this file the following values:

  • role_id with ID of "Manager Role" as returned in one of previous steps
  • group_id with ID of "Managers Group" as returned in one of previous steps
  • managed_groups should be a list of IDs, which the current user is a manager of. In our example we have a single value in this list and this ID should be replaced with ID of "Agents Group" as returned in one of previous steps.

CURL command:

curl -u apiuser:secret -H "Content-Type: application/json" -X POST --data "@add_user_peter.json" http://{host}:{port}/api/v2/users.json

If user account is created successfully, then the response message contains URL to user's data:

{"url": "/api/v2/users/34e2ac80-9201-11e5-93e4-e03f497dbdff.json"}

Repeat the same steps for user "David".

Content of file add_user_david.json:

{
    "user": {
        "name": "David",
        "is_active": true,
        "role_id": "14e1c064-cf79-11e5-9804-e03f497dbdff",
        "group_id": "7248c8f0-cf7a-11e5-adb9-e03f497dbdff",
        "timezone": "Europe/London",
        "fieldset_login": {
            "can_login": true,
            "login": "david",
            "password": "secret",
            "authenticate_type": "password"
        },
        "fieldset_recording": {
            "extensions": ["123456"],
            "record": "always",
            "record_direction": ["in", "out"]
        },
        "fieldset_licensing":
        {
            "recording_seat": true
        }
    }
}

Replace in this file the following values:

  • role_id with ID of "Agent Role" as returned in one of previous steps
  • group_id with ID of "Agents Group" as returned in one of previous steps

CURL command:

curl -u apiuser:secret -H "Content-Type: application/json" -X POST --data "@add_user_david.json" http://{host}:{port}/api/v2/users.json

FAQ

Question: Where can I find detailed description of all fields that are supported in JSON submitted data?

Answer: Our product is continuously improved and new configuration parameters may be added at any time. The documentation may be out of date. The best way is to execute the following HTTP GET requests on your MiaRec server and retrieve a complete list of currently supported parameters:

curl -u apiuser:secret http://{host}:{port}/api/v2/tenants.json
curl -u apiuser:secret http://{host}:{port}/api/v2/roles.json
curl -u apiuser:secret http://{host}:{port}/api/v2/groups.json
curl -u apiuser:secret http://{host}:{port}/api/v2/users.json

If you do not understand meaning of some parameters, for example, inside user's JSON data, then we recommend to edit user's profile settings via web-interface and see how the JSON representation changes after that.

And of course, feel free to contact us if you have any issue or question.