This documents the possibility to interact with the admin system using REST calls (GET, POST, PUT, PATCH, DELETE) allowing automation of tasks like creating projects and users.

All examples are produced using the curl utility.

General

Authentification

The system uses BASIC AUTH authentification. Logging in simply need a admin system user and you can log in with the same username password combination that you uses for normal WEB access.

Data formats and URL's

All resources can be accessed using HTML, XML or JSON formats. 

This is a separate API from the normal REST API and the base url should be the same as the admin system (i.e. https://adm-us.drofus.com/)  you are trying to access.

E.g. the link http://[admin-url]/projects gives the normal HTML project listing while and http://[admin-url]/projects.json gives the list with project and project users in JSON format(

Some resources (notable users) has dots (.) in their resource names so the .json can not be used. Be sure to send "Accept: application/json" in the header instead so (This applies to all types of clients(e.g. postman etc.). 

Setting the Accept header to "application/json" is the recommended way of getting responses in json format. .json should only be used when testing

curl -H "Accept: application/json" -s -u testadmin:testpw http://[admin-url]/users/hakonhc

will give the same as 

curl -s -u testadmin:testpw http://[admin-url]/users/hakonhc.json

Resources:

ResourceDescription
/projectsLists and manipulation of projects
/ownersListing of project owners
/usersListing and manipulation of users on the server
/databaseListing and manipulation of databases
/project_usersListing and manipulation of users in projects

Most resources responds to both GET, PATCH and DELETE

In addition we have some special endpoint for:

ResourceMETHODDescription
/node/loginsGETGet login statistics for projects for the last 5 years, grouped by type of client used(Revit, dRofus etc.)
/node/logins?from_date=2018-01-01&to_date=2019-12-31GETGet login statistics for projects for the given time period, grouped by type of client used(Revit, dRofus etc.)
/node/unique_usersGETGets number of unique users for each project for the last 5 years
/node/unique_users?from_date=2018-01-01&to_date=2019-12-31GEtGets number of unique users for each project for the given period.
/project_data?from_date=2018-01-01&to_date=2019-12-31GEtGet statstics values on projects, to_date and from_date are optional limits on date
/password/request_resetGETA post request with a valid username will trigger a password reset email
/password/resetGETUse this with a token to change password with the API
/owners/[id]/tasks/[TaskName]/run?source=[sourcedb]&copy_ids=[ids]POST

Run a given task against all databases for a given owner. TaskName is one of the following

  • CopyOverwriteExcelExportsTask: Copy given excel export identified by ids from sourcedb to all other dbs
  • CopySharedRdlReports: Copy given RDL reports identified by ids from sourcedb to all other dbs

GET Resources: Listings

ResourceDescriptionParameters
/projectsList all projects

?query=xx will list all projects contaning xx in the name

?show_all=1 to also include inactive projects

/projects/1List project with id 1
/ownersList all owners
/owners/1List owner with id 1
/usersList of all users?query=xx to search
/users/usernameList user with username
/databaseList databases
/project_users/username,projectidShow project user

Example

$ curl -s -u testadmin:testpw http://[admin-url]/projects.json?query=template|json_reformat 
[
    {
        "project": {
            "active": true,
            "contact": null,
            "created_at": "2016-11-01T09:39:14Z",
            "created_by": null,
            "database_id": "akl-test",
            "description": null,
            "gross_area": null,
            "id": 399,
            "name": "dRofus dev template",
            "no": "01",
            "owner_id": 5,
            "status": null,
            "updated": null,
            "updated_by": null,
			"unit_type": "SM" #SM for square meters or SF for square feet
        }
    },
.....

POST Resources: Creating objects

Example

This creates an owner with the name "Test" and from the return we can see that it has been assigned with ID 11

$ curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -u testadmin:testpw -d '{"owner":{"name":"Test"}}' http://[admin-url]/owners


{"owner":{"address":null,"billing_address":null,"contact":null,"id":11,"image":null,"name":"Test","network":null,"note":null,"tech_contact":null}}

Creating a new project ( POST /projects)

Creating a new project requires some special parameters. This would the minimal data to provide when creating a new project

ParameterDescriptione
new_db1 to create a new database or 0 to add project to an existing database
new_db_templateIf creating a new database, provide the database name that would be used as a template
new_db_name

If creating a new database, provide the name of the new database

existing_db_nameIf NOT creating a new database (new_db set to 0) provide the name of the existing database to add the new project to
nameName of the project
constructor

Name of the constructor/firm of the new project

description

Description of the project

owner_idID of the owner
project_type_id

Type of project. Use one of the following values    


id │ name
─┼────────────────────
1 │ Active Project
2 │ Deprecated Project
3 │ Demo
4 │ Copy / Backup
5 │ Template
6 │ Sandbox / Test
7 │ Training
8 │ Trial


All the parameters are mandatory

Example

{
  "project": {
    "new_db": "1",
    "new_db_template": "dev-template",
    "new_db_name": "rest_test",
	"project_type_id": 1, 
    "name": "REST TEST",
    "owner_id": 5,
    "description": "TEST CREATE FROM REST",
    "constructor" : "dRofus AS"
  }
}

Creating a new project user (POST /project_users)

$ curl -H "Accept: application/json" -H "Content-type: application/json; charset=UTF-8" -X POST -u testadmin:testpw -d @data.json http://[admin-url]/project_users

{"project_user":{"created_at":"2016-11-28T12:22:35Z","project_id":408,"role":null,"superuser":null,"user_role_id":null,"username":"hakonhc"}}

Where data.json contains

{
  "project_user": { "project_id": 408,"room_rights":1 },
  "user": {"username": "hakonhc", "first_name":"Håkon","last_name":"Clausen","email":"hhc@drofus.com"},
  "mail_type": "6"
}


ParameterDescriptione
project_user

project_id: ID of the project to add to

room_rights: room permission level

equipment_rights

tender_rights

consignation_rights

system_rights

modelstore_rights

superuser. Project administrator

addon_admin: BIM admin

no_web_admin_access: if user is superuser, this denies the access to the web admin

hide_price: true or false should the user see prices

user

username: Username of the user to add

first_name: First name of the user to add

last_name: Last name of the user to add

email: Email of the user to add

If the user exists, make sure that the information given is equal to the information registred on the server

mail_typeID of the email to send to the user (from /emails), "skip_email" means no email will be sent.

GET Resources: Object manipulation and more

Databases

Resource
/database/[dbname]/disableallDisables all project users in database with name dbname
/database/[dbname]/enableallEnables all project users in database with name dbname
/database/[dbname]/kickallLogs out all users in database with name dbname
/database/[dbname]/get_backup_nowDownloads a backup of the database


Users

Resource
/users/[username]/disableDisables a users so he can not log into any project
/users/[username]/enableEnables a user
/users/[username]/kickLogs out all users in database xxx
POST /users/[username]/toggle_otpToggles whether the user has to login using Multi Factor Authentication
POST /users/[username]/toggle_force_webloginToggles whether the user has to login using Modern Login/SSO

POST Resources: Toggles and other changes

Users

Resource
/users/[username]/toggle_otpToggles whether the user has to login using Multi Factor Authentication
/users/[username]/toggle_force_webloginToggles whether the user has to login using Modern Login/SSO

PUT/PATCH Resources: Updates

Resource
/projects/[id]Update project
/project_users/username,projectidUpdate project user

Example 1: Update project

$ curl -H "Accept: application/json" -H "Content-type: application/json; charset=UTF-8" -X PATCH -u testadmin:testpw -d @data.json http://[admin-url]/projects/1

Wherer data.json contains

{
  "project": {
    "name": "REST TEST",
    "description": "TEST UPDATE FROM REST",
	"active":true
  }
}

Example 2: Update project user

$ curl -H "Accept: application/json" -H "Content-type: application/json; charset=UTF-8" -X PATCH -u testadmin:testpw -d @data.json http://[admin-url]/project_user/testuser,1

Wherer data.json contains

{
  "project_user":{
	"username":"test",
	"project_id":647,
	"room_rights":1,
	"equipment_rights":3,
	"tender_rights":4,
	"room_surface_treatment_rights":4
  }
}

DELETE Resources

You also use the DELETE operation to delete most object. 

This example will delete a user in a project

curl -H "Accept: application/json" -s -u http://[admin-url]/project_users/[username],[project_id] -X DELETE

Resetting Password

Posting a json request to "/password/request_reset" with this body and a correct username will start the reset password process. The user will get a password reset request on email with a token:

// Post to {server}/password/request_reset
{
	"username": "user"
}


To actually change the password use the following json with the token from the email:

// Post to {server}/password/reset
{
	"token": "5f2pi2zW7wO3nodwWznmDQ",
	"password": "pass",
	"password_confirm": "pass"
}

Project statistics

ResourceComment
/project_dataGives project statistics over time
/project_data/latestGives you the latest project statistics for each project

Filters



from_date=[date]Only for /project_data, gives you only data where time is greater than the given date
field=[field]Only for specific field
owner=[owner_id]Only for specific owner id


Example output

{
"field": "sum_programmed_area",
"project_id": 1262,
"time": "2019-12-16T10:56:46.848+01:00",
"value": "1233.0"
},
{
"field": "sum_designed_area",
"project_id": 1262,
"time": "2019-12-16T10:56:46.848+01:00",
"value": "1176.0"
},