Introduction

BimPoint services also provide to our clients a full REST WebApi, which can be viewed https://devapi.bim-point.com/ , production version will be hosted at https://api.bim-point.com/ ; We also provide .NET WebApiClient, which can be downloaded from nuget.org ;

This documentation describes what is required to use our webapi, how to use most required methods using the WebApiClient;

Before using WebAPI

Before using BimPoint WebApi, you need to have an account with us and having projects; If you don't have or you want a demo, please contact us https://www.bim-point.com/contact ;
Once you have an account, you should be able to create account and setup permissions, which limit the scope of what can be done via webapi;
You can either generate a Refresh Token for your dev team or for third parties ( Recommended) or you can provide to them a username and password

Control

You have total control over your data; Developers can do only what you allow them to do via the WebApi; Make sure you setup properly user rights of the user, which will be used in WebApi to avoid any unpleasant surprise

Connecting to WebApi

In order to connect to webapi, you typically need to know

Your company Url
The Project Url
The provided RefreshToken Or UserName/ Password
The WebApi Url

Getting Token using username / password

Get Refresh Token

 ServiceConfiguration serviceConfiguration = new ServiceConfiguration {
      BaseUrl = "https://devapi.bim-point.com", 
       Application = "MyLovelyApplication" //strongly recommend to provide you application name
};
 OAuth2Service oAuth2Service = new OAuth2Service(serviceConfiguration );
 BpOAuth2TokenRequest tokenRequest = new BpOAuth2TokenRequest
      {
            Application = serviceConfiguration.Application,
                Email = "email@email.com",
                Password = "password",
                GrantType = BpOAuth2TokenRequest.GrantTypes.Password
 };
var tokenResponse = await oAuth2Service.GetTokenAsync(tokenRequest);

The tokenResponse will contain the a refreshtoken, expiration date and also real token

Token Expirations

Refresh token expires after 3 months
The token expires after 1hour

Getting Token using refreshtoken

Token using RefreshToken

 OAuth2Service oAuth2Service = new OAuth2Service(serviceConfiguration );
BpOAuth2TokenRequest tokenRequest = new BpOAuth2TokenRequest {
 Application = serviceConfiguration.Application,
 RefreshToken= "myrefreshtoken", 
 GrantType = BpOAuth2TokenRequest.GrantTypes.RefreshToken}; 
var tokenResponse = await oAuth2Service.GetTokenAsync(tokenRequest);

Searching for IfcItem

The most probable activity you will be doing is searching for an IfcItem; Before being able to search for ifcitems of a project, you need to understand the structure of each ifcitem.

A project is made of one or multiple ifc files http://www.buildingsmart-tech.org/specifications/ifc-overview
Each Ifc File is made of several Objects with different types, which we call in our application : IfcItem
Each IfcItem has common properties such as Id, Label, Name , GlobalId and Type.
Each IfcItem has a set of various properties;
Each property is characterized by Key, Name, Category and ValueType
In BimPoint, Each IfcItem can have two different kinds of set of properties
- READONLY properties ; these are properties extracted from Ifc File and their keys start with "pXXXX", ie p2, p3
- READWRITE properties; these properties are user properties defined by user in our system; their keys start with "upXXXX" i.e up1, up252

To search in BimPoint application, you need to know the key of each property, category and their valuetype in order to build your queries

Finding IfcItem Property Categories

Before searching, it is good to know all IfcItem Property categories; they don't change very often so you can cache them in your own database.

Finding IfcItem Property Category

serviceConfiguration.Token = tokenResponse.Token;
var categoryService = new IfcItemPropertyCategoryService(serviceConfiguration, projectUrl);
var search = new BpIfcItemPropertyCategorySearch
 {
    Take = 50,
    Skip =0,
    GetCount = true // this will give the total
  };
 var result = await this.ifcItemPropertyCategoryService.FindAsync(search);

Finding IfcItem Properties

Once you know the categories, you can also find the properties of specific category (optional); Getting properties is important as it will allow you to know the key of each of them

Finding IfcItem Properties

serviceConfiguration.Token = tokenResponse.Token;
var ifcItemPropertyService = new IfcItemPropertyService(serviceConfiguration, projectUrl);

// The BpIfcItemPropertySearch has more option which can find
var search = new BpIfcItemPropertySearch
{
   Take = 50,
   GetCount = true,
   Categories = new List<string>{"Object"} // this is optional
 };
var result = await ifcItemPropertyService.FindAsync(search);
//The above code will return properties in categories Object. you have full info about each returned property

Finding IfcItemUserProperty Categories and Properties

Similar to readonly properties and categories, you can also find the user properties and categories

Finding User Properties and Categories

serviceConfiguration.Token = tokenResponse.Token;
var userCategoryService= new IfcItemUserPropertyCategoryService(serviceConfiguration, projectUrl);
var ifcItemUserPropertyService =new IfcItemUserPropertyService(serviceConfiguration, projectUrl);
var search = new BpIfcItemUserPropertyCategorySearch
{
Take = 50,
Skip =0,
GetCount = true // this will give the total
};
var result = await this.userCategoryService.FindAsync(search);

//get user properties of the project
var result2 = await ifcItemUserPropertyService.FindAsync(new BpIfcItemUserPropertySearch
 {
   Active = true,
   GetCount = true,
   Categories = new List<string> { "CEO" },
   Take = 10
  });

Finding IfcItems

Once you know properties, categories , user properties and user property categories, finding IfcItem is easy; The Search object provides great flexibility;

Property keys

Remember, in criterias or properties to be returned, property keys are either Pxxx or UPXXX
We have well known properties keys such as : "name", "label", "globalid", "id", "type"

Example 1 : Find All With Criteria Include Properties By Categories

Finding IfcItems Example 1

//given that the serviceConfiguration is properly initialized as above
var ifcItemService = new IfcItemService(serviceConfiguration, projectUrl);

// Example find with criteria and include properties withing specific categories
var searchObject = new BpIfcItemSearch
   {
     Take = 10,
     GetCount = true
};
searchObject.Criterias.Add(new BpIfcItemSearchCriteria
 {
    Key = "type",// well known key
    Value = "IfcFlowSegment",
    Operator = BpIfcItemSearchCriteriaOperator.Eq
});
//Properties to be returned are by specified categories
searchObject.IfcPropertiesOption.Include = BpIfcItemPropertyOptionInclude.Categories;
//when include is categories, then we will return properties within the categories below; all are key sensitive.
searchObject.IfcPropertiesOption.Categories = new List<string> { "Object", "Elektroinstalace" };
var result = await this.ifcItemService.FindAsync(searchObject);

Example 2: Find All With Criteria. Include specifics properties, user properties and calculate Sum of some properties number properties

Finding IfcItems Example 2

var searchObject = new BpIfcItemSearch
 {
   Take = 10,
   GetCount = true
};
searchObject.Criterias.Add(new BpIfcItemSearchCriteria
{
  Key = "p412",
  Value = 0,
  Operator = BpIfcItemSearchCriteriaOperator.Gt
});
searchObject.IfcPropertiesOption.Include = BpIfcItemPropertyOptionInclude.Keys; // we want to include specific properties
searchObject.IfcPropertiesOption.Keys = new List<string> { "p411", "p778", "p413", "p419", "p422", "p426" };
searchObject.SumUpPropertyKeys = new List<string> {"p411", "p778", "p413", "p419", "p422", "p426"};// we want also to calculate the sum of listed properties
searchObject.UserPropertiesOption.Include = BpIfcItemPropertyOptionInclude.Keys; // we want to include specific user properties
searchObject.UserPropertiesOption.Keys = new List<string> {"up16", "up3"};
var result = await this.ifcItemService.FindAsync(searchObject);

Practical Info

BpIfcItemSearch

Property	Note
GlobalIds	list of unique identifiers you want to limit the search too
Ids	list of unique ids you want to limit the search to; the ids are internal ids generated by our application; this can change whenever the ifc files are reimport
Labels	internal ids used in the graphical representation in our main applications;
Criterias	List of criterias; all criterias are executed using AND operators
IfcPropertiesOption	Allow you to specific which properties to be included : either you specifically list keys or categories or none of them (which is default)
UserPropertiesOption	Allow you to specific which user properties to be included: either by keys, categories or none
SumUpPropertyKeys	It will calculates the sum of specified keys; only number types
GetCount	if you want us to give you the total count , set this value to true
Take	how many row you want back
Skip	From which number you want the take to start from
SortBy	Expected a property key
OrderBy	asc or desc

BpIfcItemSearchCriteriaOperator

Operator

   public class BpIfcItemSearchCriteriaOperator
   {
       public const string Contains = "contains";
       public const string Eq = "eq";
       public const string Exists = "exists";
       public const string Gt = "gt";
       public const string Gte = "gte";
       public const string Lt = "lt";
       public const string Lte = "lte";
       public const string Ne = "ne";
       public const string StartWith = "startwith";
    }

BpIfcItemPropertyOptionInclude

Include Options

 public class BpIfcItemPropertyOptionInclude
    {
        public static List<string> AllValids = new List<string> { All, None, Categories, Keys };

        public const string All = "all";
        public const string None = "none";
        public const string Categories = "categories";
        public const string Keys = "keys";
    }

IfcItem Types

The list of ifcitem types are per ifc specification and it can be found here http://www.buildingsmart-tech.org

User Properties Management

If your permissions allow you, you should be able to create user properties for the project; User properties are grouped by Category and SubCategory; Your permission may allow you to only create user properties of specific categories only; SubCategories can be freely defined and they are used mainly to organize displaying in our main application

To create and query user properties, you need to use IfcItemUserPropertyService

User Properties

 var ifcItemUserPropertyService = new IfcItemUserPropertyService(serviceConfiguration, projectUrl);
// to get one user proper info knowing the key
var udp = await ifcItemUserPropertyService.GetAsync("up1");

//to create a new user property
 var newUdp = new BpNewIfcItemUserProperty
 {
    Name = "Project Start Date",
    Active = true,
    Category = "Global", // the default Category of user property; this value depends on your permissions
    SubCategory = "Dates", // free text
    ValueType = "date",
    Index = 10 // display order in UI
 };
var createdUpd = await ifcItemUserPropertyService.CreateAsync(newUdp);

Set / Update User Properties Value of IfcItems

User properties of IfcItem ( started with UPxxx) can also be updated via API; All depends of your permissions; We require the GlobalId as the unique identifier of the each element to be updated;

Update one

Set / Update User Properties Values

//Let find a random item where we want to update the user properties
var searchObject = new BpIfcItemSearch
 {
  Take = 1,
 GetCount = false
 };

//let get only the user properties keys we want to update
searchObject.UserPropertiesOption.Include = BpIfcItemPropertyOptionInclude.Keys;
searchObject.UserPropertiesOption.Keys = new List<string> { "up15", "up1", "up2", "up5" };
var result = await this.ifcItemService.FindAsync(searchObject);
var ifcItem = result.Items[0];

//let update the value of the user properties with random numbers
var propertyValue = new BpIfcItemUserPropertyValue();

var now = DateTime.UtcNow;
propertyValue.GlobalId = ifcItem.GlobalId; //this is required

propertyValue.Properties["up15"] = new Random().Next(1000); // up15 is an integer
propertyValue.Properties["up1"] = "Inv" + Guid.NewGuid().ToString(); //string
propertyValue.Properties["up2"] = "Klic" + Guid.NewGuid().ToString(); //string
propertyValue.Properties["up5"] = DateTime.UtcNow.Date.AddHours(now.Hour).AddMinutes(now.Minute); // a date

//Update that items; when success, 200 Code is returned so no exeption
 var UpdateResponse = await this.ifcItemService.UpdateAsync(propertyValue);

//Let get back the ifcitem and check if values where really updated
searchObject.GlobalIds = new List<string> { ifcItem.GlobalId }; // that is how we get specific item

var result2 = await this.ifcItemService.FindAsync(searchObject);
var ifcItemUpdated = result2.Items[0];
Assert.Equal(Convert.ToInt32(propertyValue.Properties["up15"]), Convert.ToInt32(ifcItemUpdated.Properties["up15"]));
Assert.Equal(propertyValue.Properties["up1"], ifcItemUpdated.Properties["up1"]);
Assert.Equal(propertyValue.Properties["up2"], ifcItemUpdated.Properties["up2"]);
Assert.Equal(propertyValue.Properties["up5"], ifcItemUpdated.Properties["up5"]);

Bulk Updates

If you have multiple items to be updated , Bulk is suitable method for you

Bulk Updates of IfcItems

//let randomly find 10 items which we will update user properties using bulk method

var searchObject = new BpIfcItemSearch
        {
       Take = 10,
       GetCount = false
  };

//let include only user properties which we want to updates
searchObject.UserPropertiesOption.Include = BpIfcItemPropertyOptionInclude.Keys;
searchObject.UserPropertiesOption.Keys = new List<string> { "up15", "up1", "up2", "up5" };

//find
var result = await this.ifcItemService.FindAsync(searchObject);

//let create the BpBulkIfcItemPropertyValue object which is used for bulk operation
BpBulkIfcItemPropertyValue bpBulkIfcItemPropertyValue = new BpBulkIfcItemPropertyValue();

//let update the 10 items with random values
var rand = new Random(10);
foreach (var ifcItem in result.Items)
{
  var now = DateTime.UtcNow;
  //one update
  var propertyValue = new BpIfcItemUserPropertyValue();
  propertyValue.GlobalId = ifcItem.GlobalId; //always required
  propertyValue.Properties["up15"] = rand.Next(1000);
  propertyValue.Properties["up1"] = "Inv" + Guid.NewGuid().ToString();
  propertyValue.Properties["up2"] = "Klic" + Guid.NewGuid().ToString();
  propertyValue.Properties["up5"] = DateTime.UtcNow.Date.AddHours(now.Hour).AddMinutes(now.Minute).AddSeconds(now.Second);
 
  // Add to bulk
  bpBulkIfcItemPropertyValue.Items[ifcItem.GlobalId] = propertyValue;
 }

//Execute bulk operation
var bulkUpdateResponse = await this.ifcItemService.BulkUpdateAsync(bpBulkIfcItemPropertyValue);
//When the operation success, items is always empty; otherwise, it will contain the result of each element so you can know which one successes, which one fails
Assert.Empty(bulkUpdateResponse.Items);

//Let read back the updated items           
searchObject.GlobalIds = bpBulkIfcItemPropertyValue.Items.Keys.ToList();

 var result2 = await this.ifcItemService.FindAsync(searchObject);
           
 foreach(var ifcItemUpdated in result2.Items)
  {
     var propertyValue = bpBulkIfcItemPropertyValue.Items[ifcItemUpdated.GlobalId];
     Assert.Equal(Convert.ToInt32(propertyValue.Properties["up15"]), Convert.ToInt32(ifcItemUpdated.Properties["up15"]));
     Assert.Equal(propertyValue.Properties["up1"], ifcItemUpdated.Properties["up1"]);
     Assert.Equal(propertyValue.Properties["up2"], ifcItemUpdated.Properties["up2"]);
     Assert.Equal(propertyValue.Properties["up5"], ifcItemUpdated.Properties["up5"]);
  }

Contact

If you have any issues using the webapi client, drop an email to devteam@bim-point.com

Documentations

BimPoint WebApi Client