Create a Security Role
{ createRole }
Adds a new security role to the system.
Method
/API2/access/createRole
- Enterprise Admin
Input Parameters
Name
roleData
Object Type
Description
An object for defining which user is attached to a role.
Output Response
Successful Result Code
200
Response Type
Description of Response Type
Generic API response object with success or failure flag and related messages.
Notes
The added role is simply a shell. Use 'AddUserToRole' method to attach users to the role to make it effective.
Examples
Create new database user (JavaScript):
This example demonstrates how to create a new tenant, user and roles in Pyramid, when using database authentication.
The example uses API authentication driven from JavaScript. See Authentication APIs for alternatives.
// URL of the Pyramid installation and the path to the API 2.0 REST methods
var pyramidURL = "http://mysite.com/api2/";
// step 1: authenticate admin account and get token
// NOTE: callApi method is a generic REST method shown below.
let token = callApi("auth/authenticateUser",{
"data":{
"userName":"adminUser1",
"password":"abc123!"
}
},false);
log("got token "+token);
// step 2: create a new tenant to house new users
let createTenantResult = callApi("access/createTenant",{
"tenant": {
"name": "Test Tenant 1", //tenant caption
"viewerSeats": 1, //number of allocated seats
"proSeats": 1 //number of allocated seats
},
"auth": token // admin token generated above
});
// step 3: get auto generated tenant ID from step 2 result.
let tenantId = createTenantResult.data.modifiedList[0].id;
log("created tenant, id= "+tenantId);
// step 4: create new user in new tenant. using DB method, because using local db authentication
let createUser = callApi("access/createUserDb",{
"user": {
"userName": "user1",
"password": "1234",
"firstName": "first",
"lastName": "last",
"email": "email@pyramidanalytics.com",
"adminType": 0, //admin type enumeration: normal user
"clientLicenseType": 100, //license type enumeration: viewer
"tenantId": tenantId //tenant Id from previous step
},
"auth": token // admin token generated above
});
// step 5: get auto generated user ID from step 4 result.
let userId = createUser.data.modifiedList[0].id;
log("created user "+userId);
//step 6: optional step to update user's first name
let updateUser=callApi("access/updateUsersDb",{
"user":[{
"id":userId,
"firstName":"new first name"
}],
"auth": token
});
//step 7: create new role in tenant
let createRole=callApi("access/createRole",{
"data": {
"roleName": "new role",
"isHidden": false, // hidden roles appear only in the admin - not for end users.
"tenantId": tenantId
},
"auth": token
});
// step 8: get auto generated role ID from step 7 result.
let roleId = createRole.data.modifiedList[0].id;
log("created role "+roleId);
// step 9: associate user with role
let addUserToRole = callApi("access/addUserToRole",{
"data": {
"userId": userId,
"roleId": roleId
},
"auth": token
});
log("addUserToRole was sucsseful since errorMessage is empty "+addUserToRole.data.errorMessage.length==0);
// ##### optional generic logging method for debugging ##############
function log(msg){
document.write(msg);
console.log(msg);
}
// ##### generic REST API calling method ##############
function callApi(path,data,parseResult=true){
var xhttp = new XMLHttpRequest();
xhttp.open("POST", pyramidURL+path, false);
xhttp.send(JSON.stringify(data));
if(parseResult){
return JSON.parse(xhttp.responseText);
}else{
return xhttp.responseText;
}
}