For the past seven years, the Unifi team has been working diligently to build the most robust BIM content management system in the AECO industry, Unifi Pro. Our product is arguably the most popular solution across the industry to help firms gain control over the organization of their digital assets as well as visibility of Revit family parameter data.
Last year we followed up with our second offering to the AECO space, Project Analytics, which provides insight to the BIM data encapsulated within Revit projects. One of the primary goals of Project Analytics is to give non-BIM stakeholders the ability to review the data and contents of a model which gets our industry one step closer to overcoming one our biggest technological hurdles to date, which is lack of model transparency.
Data Management is Content Management at Scale
By starting with BIM content in Unifi Pro and then progressing to project models with Project Analytics, it’s clear that we’ve taken intentional steps to help the industry gain visibility of their BIM data. With the groundwork laid down for reviewing this data, the next obvious step in managing that data is to have the ability to modify it.
Technically speaking, manipulating data can be as simple as changing parameter values in a Revit family or Revit project. Come to think of it, we’re managing data on a daily basis while we virtually construct buildings using BIM.
But this begs a few questions:
•Are your workflows scaleable?
•How would a firm go about changing their parameter data in a library of 1,000 Revit families?
•Can you truly manage your data if you can’t handle it programmatically?
Undoubtedly, you would either need to use a Revit add-in or develop a custom script (Dynamo or other) to handle these changes in large batches. Even with some sort of Revit add-in or Dynamo graph, there would still be a need to handle these changes using your local machine.
API’s Are So Hot Right Now
API stands for “application programming interface,” but I suspect that spelling it out doesn’t help some of our readers understand what an API actually is. The easiest way to explain an API is to simply rearrange the letters a bit.
Simply put, an API helps you Interface with an Application using Programming. In other words, it’s one way that software developers can use their own code to control another piece of software.
A full explanation of an API is beyond the scope of this post, but if you would like to learn more about REST API’s, check out this REST API tutorial.
Introducing Unifi’s Content Management API
Now think back to one question that was presented earlier in this post. If you needed to add a parameter to 1,000 families in batch, leveraging some sort of an API would be the most efficient way to handle this task.
Luckily for our users, we’ve launched our Content Management API which provides read/write access to their entire content library simply by using simple textual requests formatted in JSON. With this API, users will have the ability to access their content data and even manage the parameters within their Revit families.
Best of all, since you’re using a REST API, these batches of changes will be handled in the cloud, rather than on your local machine.
Get to the (end)point.
Our latest API documentation is posted at apidocs.unifilabs.com. Here, you will find detailed descriptions of our API endpoints, complete with sample code for requests and responses. Let’s cover just a few operations for the /batch endpoint that are designed to help you manage your Revit family parameter data at scale.
CreateParameter
This operation will add a Revit parameter to a Revit family in your libraries. By simply specifying a few required properties to the body of your request, you have the ability to add a parameter to your Revit families in the cloud.
{ "type": "object",
"properties": {
"ObjectId": {
"description": "The ID of the File to modify. The modification will be to the currently active revision of the file.",
"type": "string"
},
"RevitYear": {
"description": "Revit year of the version to update.",
"type": "integer"
},
"Operation": {
"type": "string",
"const": "CreateParameter"
},
"Name": {
"description": "Parameter Name, must meet all Revit requirements.",
"type": "string"
},
"Guid": {
"description": "Shared parameter GUID value.",
"type": "string"
},
"ReplaceParameter": {
"description": "If true or omitted, and the family contains a parameter of the same name, it will be replaced with the new parameter. If false and the family contains a parameter of the same name, the operation will fail.",
"type": "boolean",
"default": true
},
"InstanceParameter": {
"description": "If true, the parameter will be an instance parameter. If false or omitted, it will be a family parameter.",
"type": "boolean",
"default": true
},
"Type": {
"description": "Data type of parameter, exactly as it would appear in a Revit shared parameter file.",
"type": "string"
},
"Group": {
"description": "The name of the parameter group in which this parameter will appear in Revit, exactly as displayed in Revit. Defaults to Other unless ReplaceParameter is true and there is an existing parameter of the same name that is being replaced, in which case the group of that parameter will be used.",
"type": "string"
},
"Value": {
"description": "A standard Revit value string, which may include unit indicators as acceptable to Revit. If the value starts with an = sign, the parameter's formula will be set to the value after the =, otherwise the parameter's value is set. If this is an instance parameter, this sets the default value of the parameter. If Value does not start with =, the family uses a type catalog, and the affected parameter appears in the type catalog, all values for this parameter in the type catalog will be set to Value.",
"type": "string"
}
},
"required": ["Guid", "Name", "ObjectId", "Operation", "RevitYear", "Type"],
"additionalProperties": false
}DeleteParameter
This operation removes a parameter from a Revit family. Note that you’ll need to specify the required properties as noted in the code snippet below.
Again, additional information is available in more detail at apidocs.unifilabs.com.
{ "type": "object",
"properties": {
"ObjectId": {
"description": "The ID of the File to modify. The modification will be to the currently active revision of the file.",
"type": "string"
},
"RevitYear": {
"description": "Revit year of the version to update.",
"type": "integer"
},
"Operation": {
"type": "string",
"const": "DeleteParameter"
},
"Name": {
"description": "Name of parameter to delete. May be a family parameter.",
"type": "string"
},
"Guid": {
"description": "GUID of shared parameter to delete.",
"type": "string"
}
},
"required": ["Guid", "Name", "ObjectId", "Operation", "RevitYear"],
"additionalProperties": false
}
SetValue
This operation sets the value of an existing parameter in a Revit family.
{
"type": "object",
"properties": {
"ObjectId": {
"description": "The ID of the File to modify. The modification will be to the currently active revision of the file.",
"type": "string"
},
"RevitYear": {
"description": "Revit year of the version to update.",
"type": "integer"
},
"Operation": {
"type": "string",
"const": "SetValue"
},
"ExistingName": {
"description": "Parameter name.",
"type": "string"
},
"ExistingGuid": {
"description": "Shared parameter GUID value.",
"type": "string"
},
"Value": {
"description": "A standard Revit value string, which may include unit indicators as acceptable to Revit. If the value starts with an = sign, the parameter's formula will be set to the value after the =, otherwise the parameter's value is set. If this is an instance parameter, this sets the default value of the parameter. If Value does not start with =, the family uses a type catalog, and the affected parameter appears in the type catalog, all values for this parameter in the type catalog will be set to Value.",
"type": "string"
}
},
"required": ["Guid", "Name", "ObjectId", "Operation", "RevitYear"],
"additionalProperties": false
}
Do you have any ideas on what should be built with our API?
I have some side projects for sample applications (including some Zero Touch nodes for Dynamo). I’ve been cooking these up in preparation for the release of our API’s and I can’t wait to share them with you all.
Until my side projects are fully-baked, drop me a line in the comments below and let me know if you have an idea for an application that you’d like to see built. Better yet, let us know if you’ve already built something on our API. We want to hear from you!