Define API release notes

• A new endpoint is available for getting classification codes by batch templates and classification group:
  • /api/v3/{contextGuid}/templates/classifications/{guid}/classification-codes

• Clients of Templates API can now see an indication that content is archived

• Templates API endpoints are extended with information about Owner context (source):​
  • List and relations endpoints response model is extended with information about the Owner context. Both context Owner name and Owner context GUID are included.​
  • Details endpoints response model is extended with information about the Owner context GUID.​
  • A new endpoint is available providing a list of available Owner contexts.

• Clients of Templates API are now able to get properties and generic properties for a list of templates and selected prerequisite (milestone/purpose/actor)​
• VersionGuid query parameter and response property are now deprecated in Templates API​

• Clients are now able to get the context specific attributes of Construction objects, References and Properties. Single and batch endpoints are available.​
• Clients are now able to get properties and generic properties for a list of templates and selected prerequisite (milestone/purpose/actor) in Templates API.​
• Deprecated Version GUID response property is now removed.​

1. Clients of Templates API are now able to get a list of predefined values by property and a list of Groups of Properties:​
   • /api/v3/{contextGuid}/groups-of-properties/generic-properties/{Guid}/predefined-values
   • /api/v3/{contextGuid}/groups-of-properties/properties/{Guid}/predefined-values

Templates API v.3.16.0

What’s new in this version:

1. Clients are now able to get mappings for a list of properties in a data template:
   • GET/api/v3/{contextGuid}/templates/{guid}/generic-properties/mappings
   • GET/api/v3/{contextGuid}/templates/{guid}/properties/mappings

Templates API v.3.15.0

What’s new in this version:

1. Indicate which is the latest approved version when getting related parent concepts – clients can now easily see which is the latest approved version of the parent concept:
   • The response of the following endpoints has been extended with ‘isLatest’ flag:
     • GET /api/v3/{contextGuid}/classifications/{versionGuid}/templates
     • GET /api/v3/{contextGuid}/classification-codes/{versionGuid}/classifications
     • GET /api/v3/{contextGuid}/construction-objects/{versionGuid}/templates
     • GET /api/v3/{contextGuid}/generic-properties/{versionGuid}/properties
     • GET /api/v3/{contextGuid}/generic-properties/{versionGuid}/groups-of-properties
     • GET /api/v3/{contextGuid}/groups-of-properties/{versionGuid}/templates
     • GET /api/v3/{contextGuid}/labels/{versionGuid}/groups-of-properties
     • GET /api/v3/{contextGuid}/measures/{versionGuid}/generic-properties
     • GET /api/v3/{contextGuid}/properties/{versionGuid}/groups-of-properties
     • GET /api/v3/{contextGuid}/references/{versionGuid}/templates
     • GET /api/v3/{contextGuid}/references/{versionGuid}/properties
     • GET /api/v3/{contextGuid}/units/{versionGuid}/measures
     • GET /api/v3/{contextGuid}/units/{versionGuid}/generic-properties
     • GET /api/v3/{contextGuid}/units/{versionGuid}/properties
   • Corresponding batch endpoints have been extended as well;
   • If the latest approved version of the parent concept is not related, the flag will be false for all related concepts.
2. Bug fixing and regular maintenance

Templates API v.3.10.0

What’s new in this version:

• New endpoint is now available where ‘documents’ is renamed to ‘references.
• New endpoint is now available where ‘property tag’ is renamed to ‘label’.

Old endpoints have been marked as deprecated and will be available for 3 months, so clients have enough time to switch to the new ones. After that period ends, the deprecated endpoints will be removed from the API services.

More details can be found in Cobuilder Developers portal

Templates API v.3.7.0

What’s new in this version:

• New endpoint is now available to get list of published templates – Get published templates by name and context guid | link
  • Clients can now get the published template versions or the full list of all approved templates with their versions
  • Access can be restricted so certain clients get access only to published versions of the templates
• Templates details endpoint is extended with information on whether a template is published – Get template details by template version guid and context guid | link
  • Clients can now see in the API if a template version has been published

Templates API v.3.6.0

What’s new in this version:

1. Concept details response model now includes minor and major versions

Templates API v.3.5.0

What’s new in this version:

1. Clients of Templates API v2 can now see in the Developers portal and the response header that v2 is deprecated and will be supported until March 2023
2. All approved concept versions are returned when getting related concepts

Templates API version (v 3.1.0) is now available

Business:

1. Flexibility – cover various use cases (like integrations with different construction data management solutions such as BIM authoring tools, PIM systems, 3D modelling, ERP and more)
2. Scalability – reducing the effort for creating new endpoints
3. Performance – reducing the time for returning data
4. Consistency and transparency – exposing the content in a more consistent and transparent way

Technical details:

Template Requirements

1. Get milestone generic properties of template by template version guid, milestone version guid and context guid.
2. Get milestone properties of template by template version guid, milestone version guid and context guid.
3. Get purpose generic properties of template by template version guid, purpose version guid and context guid.
4. Get purpose properties of template by template version guid, purpose version guid and context guid.
5. Get generic property milestones of template by template version guid, generic property version guid and context guid.
6. Get property milestones of template by template version guid, property version guid and context guid.
7. Get generic property purposes of template by template version guid, generic property version guid and context guid.
8. Get property purposes of template by template version guid, property version guid and context guid.
9. Get predifined values of generic-property in the context of a template by template version guid, generic-property version guid and context guid.
10. Get predifined values of a property in the context of a template by template version guid, generic-property version guid and context guid.

Template Mappings

1. Get mapped properties of template by template version guid and context guid.
2. Get mapped generic properties of template by template version guid and context guid.
3. Get generic property mapped classifications with their classification codes of template by template version guid, generic property concept guid guid and context guid.
4. Get mapped properties with their classification codes of template by template version guid, classification version guid and context guid.

Predefined values of properties and generic properties:

1. Get generic property related predefined values of the group of properties by group of properties version guid, generic property version guid and context guid
2. Get property related predefined values of the group of properties by group of properties version guid, property version guid and context guid

Dependencies of properties and generic properties:

1. Get generic property related dependencies of the group of properties by group of properties version guid, generic property version guid and context guid
2. Get property related dependencies of the group of properties by group of properties version guid, property version guid and context guid

Classifications:

1. Get classifications by classification-code version guid, and context guid
2. Get templates by classification-code version guid, and context guid

Detailed documentation can be found at Cobuilder Developer Portal.

A new Templates API version v2.21.0 was released.

Templates API now exposes information related to Purposes and Milestones – feature in Define that was released in July 2022. In short now developers can:

1. Get list of all Purposes or Milestones
2. Get details for a given Purpose or Milestone
3. Get list of a all Purposes or Milestones related the properties inside of a Data Template
4. Get list of properties in a Data Template, related to a given Purpose or Milestone
5. Get list of Data templates related to a given Purpose or Milestone (Data Templates that have properties that are related to the given Purpose or Milestone)

Technical details:

Whole group of endpoints for requiring information about Purposes

1. New endpoint – Get Purpose list | link
   • Use this endpoint to get a list with all approved Purposes in the context or return filtered list by provided purpose name, i.e. ‘LCA’ will return all purposes containing ‘lca’ in their name
2. New endpoint –  Get Purpose details | link
   • Use this endpoint to receive the details for a specific Purpose
3. New endpoint –  Get template’s purposes by Template version guid (Get purposes of template.) | link
   • Use this endpoint to receive a list of all purposes that have relation to the given Data Templates
4. New endpoint –  Get Data Template’s properties by given Purpose (Get properties of purpose) | link
   • Use this endpoint to receive a list of properties belonging to a given Data Template and a given Purpose
5. New endpoint –  Get Data Template’s purposes for a property (Get purposes of property) | link
   • Use this endpoint to receive a list with purposes related to a given property within a given Data Template
6. New endpoint –  Get list of Data Templates by given Purpose | link
   • Use this endpoint to receive a list with all approved Data Templates that have at least one property specified with the given purpose

Whole group of endpoints for requiring information about Milestones (analogical to the Purposes)

1. New endpoint – Get Milestones list | link
   • Use this endpoint to get a list with all approved Milestones in the context or return filtered list by provided milestone name, i.e. ‘RIBA’ will return all milestones containing ‘riba’ in their name
2. New endpoint –  Get Milestone details | link
   • Use this endpoint to receive the details for a specific Milestone
3. New endpoint –  Get template’s milestones by Template version guid (Get milestones of template.) | link
   • Use this endpoint to receive a list of all milestones that have relation to the given Data Templates
4. New endpoint –  Get Data Template’s properties by given Milestone  (Get properties of milestone) | link
   • Use this endpoint to receive a list of properties belonging to a given Data Template and a given Milestone
5. New endpoint –  Get Data Template’s milestones for a property (Get milestones of property) | link
   • Use this endpoint to receive a list with milestones related to a given property within a given Data Template
6. New endpoint –  Get list of Data Templates by given Milestone (Get templates of milestone) | link
   • Use this endpoint to receive a list with all approved Data Templates that have at least one property specified with the given milestone

A new Templates API version v2.21.0 was released.

Now the following capabilities for getting data from Define via the API are available:

• Getting data related to Reference documents (Standards) – list with documents in the context, details of a document, related properties to a document, related data templates to a document
• Getting data related to Construction objects – list of objects in the context, details of a construction object, related data templates to a construction object

Technical details:

The whole group 4. Search Data Templates via Reference document

1. New endpoint – Get all documents by name | link
   • Use this endpoint to get a list with all reference documents (standards) in the context, OR to get a filtered list by provided document name, i.e. ‘window’ will return all documents containing ‘window’ in their name
2. New endpoint –  Get reference document’s details | link
   • Use this endpoint to receive the details for a reference document
3. New endpoint – Get templates by reference document version guid | link
   • Use this endpoint to receive a list of data templates that are connected to a given reference document (standard)
4. New endpoint – Get properties by reference document version guid | link
   • Use this endpoint to receive a list with all properties that are linked to a reference document (standard)

The whole group 6. Search in Data Template by CO

1. New endpoint – Get construction objects by name | link
   • Use this endpoint to get a list with all construction objects or to get a filtered list by provided name, i.e. ‘Window’ will return all objects containing ‘window’ in their name
2. New endpoint – Get construction object details | link
   • Use this endpoint to receive the details for a construction object
3. New endpoint – Get templates by construction object version guid | link
   • Use this endpoint to receive a list of data templates that are connected to a given construction object
4. New endpoint – Get construction object by template version GUID | link
   • Use this endpoint to receive the construction object for a Data Template

The Templates API now supports the mapping functionality released last week (IFC, Revit properties, etc). Two new endpoints were developed to fetch all mapped properties in a specific Data Template.

Technical details:

1. New endpoint – Get mapped properties by template version guid | link
   • Use this endpoint to get a list with properties in the DT that have mappings
2. New endpoint – Get property mappings by template version and property concept guid | link
   • Use this endpoint after the previous one to return the mappings per each property

This release enhances the workflows from 1 April 2022. Developer users can now get details on classifications by their version GUID. Also Czech language is supported now in the API. The content translated in this language can be accessed via culture code “cs-CZ” in the API endpoints.

Technical details:

1. New endpoint – Get classification details | link
2. Added Czech language to the API – no change to the endpoints or their request-responses model, this is implemented solely in the backend and should not affect the clients who have integrated with Templates API.

This release enhances the workflows from 8 March 2022. The API can now return the list of all classifications in a context and provide option to search Data Templates by classification codes. Another enhancement is to get all the classifications for a specific Data Template.

Technical details:

1. New endpoint – Get classifications list | link
   • Returns list with all classifications in the context
2. New endpoint – Get classifications that have codes mapped to a template | link
   • Returns the classifications related to a Template
3. Extended endpoint – Get Templates List – filtered by matching classification code | link
   • Added 3 optional parameters to return templates which are classified by the provided classification code.- ClassificationVersionGuid – if provided, ClassificationCodeVersionGuid becomes required parameter
     – ClassificationCodeVersionGuid – if provided, ClassificationVersionGuid becomes required parameter
     – include-nested – optional, if missed, the default values is false(default) – returns templates that match only the provided code, true – returns templates that match this code and all child codes
   • Note: The two parameters ClassificationVersionGuid  and ClassificationCodeVersionGuid go together – one cannot be provided without the other

Developers can get information about all versions for a concept. They can also start extracting information from a list of all properties and work with this list or a sole property.

Technical details:

1. New endpoint – Get properties by name | link
   • New endpoint in Templates API that returns properties filtered by property full name, based on the passed culture (if no culture info is provided, take the default one)
2. New endpoint – Get templates by property version guid  | link
   • New endpoint to fetch templates data for a property by property version GUID
3. New endpoint – Get referenced document by property version guid | link
   • New endpoint to return document, referenced for a property. A property can be without document or with only one
4. New endpoint – Get concept versions by concept version guid  | link
   • New endpoint to get all concept versions by concept version guid which is approved (and shared)

We have enriched the information that can be read for property’s unit and measure as well as more details on the properties within a data template.

Technical details:

1. New endpoint – Get unit details by version guid | link
2. Modified and Extended endpoint – Get properties of template | link
   • The logic for taking the data is the same as with the existing endpoint.
     We have only added:
     – all the translations for property in default English and in the given language code
     – flag whether the property has predefined values
     – in the property set uses (property tags) are added version guid and default name in default English
3. Extended endpoint – Get measure details | link
   • New endpoint to return document, referenced for a property. A property can be without document or with only one

Now the API can find property dependencies in a Data Template, very useful for cases with EPD properties (Environmental Product Declarations). In addition, users can get information on what the property’s measure and unit are.

Technical details:

1. Implement changes in endpoint about property dependencies | link
2. Get property measures | link
3. Get units of a measure | link

Get detailed information on a property by its GUID.

Technical details:

1. Get property details by version GUID | link

Developers can get information about all versions of a concept. They can also start extracting information from a list of all properties and work with this list or a single property.

Technical details:

1. New endpoint – Get properties by name | link
   • New endpoint in Templates API that returns properties filtered by property full name, based on the passed culture (if no culture info is provided, take the default one)
2. New endpoint – Get templates by property version guid | link
   • New endpoint to fetch templates data for a property by property version GUID
3. New endpoint – Get referenced document by property version guid | link
   • New endpoint to return document, referenced for a property. A property can be without document or with only one
4. New endpoint – Get concept versions by concept version guid | link
   • New endpoint to get all concept versions by concept version guid which is approved (and shared)

Now users can retrieve information about Tags in Define and search properties and templates by tag.

Technical details:

1. New endpoint – Get property tags by name | link
   • Gets the list of all tags
   • Returns filtered list by tag name
2. New endpoint – Get property tag by property tag version guid | link
   • Gets details of a tag
3. New endpoint – Get properties by property tag version guid and optional template version guid | link
4. New endpoint – Get templates by property tag version guid | link

Now users can search via the API information about Classifications and Classifications Codes in Define. Additional options to search data templates by classification codes, get lists and details on classifications will be made available in upcoming releases.

Technical details:

1. New endpoint – Get classification codes that are mapped to a template | link
   • Expose information about Template’s Classifications
   • Known issue: the typo in the endpoint name.
2. New endpoint – Get classification code details by classification group version guid and classification code version guid | link
   • Get information about a classification code and its direct children codes
3. New endpoint – Get classification codes by search terms (name, classNumber) | link
   • Get/Search classification codes in a classification by name and/or class number