DCOM Rule Engine API

Base URL: /v1/, Version:

This is the API that is implemented by a DCOM Rule Engine to connect to it. version: '1.0.0'

Default request content-types: application/json, application/xml
Default response content-types: application/json, application/xml
Schemes: https

Summary

Path Operation Description
/v1/ GET

Retrieves the basic metadata about the Rule Engine
PUT

Initialises a compliance check
/v1/{complianceCheckUID} GET

Returns an overview of the project entities that the rule engine is aware of and the data required for them
POST

Updates the ID Set used within the Rule Engine
/v1/{complianceCheckUID}/answers POST

Enables the submission of answers to compliance questions to the rule engine
/v1/{complianceCheckUID}/approval POST

Enables the signalling of approval (or not) and the transmission of associated conditions with an approval to the rule engine for onward transmission to the result service.
/v1/{complianceCheckUID}/bcf GET

Enables the retrieval of a BCF File documenting any issues identified by the rule engine as part of the checking process
/v1/{complianceCheckUID}/data POST

Enables the submission of compliance data to the rule engine to the implementing service.
/v1/{complianceCheckUID}/messaging PUT

Enables the sending of a message to the other parties in the compliance checking process
/v1/{complianceCheckUID}/results GET

Returns a list of all compliance results from a given compliance check
POST

Enables the submission of compliance results to the rule engine. This is used for the manual specification of top level results where automated computation is not possible
/v1/{complianceCheckUID}/{clauseId} GET

Retrieves feedback on a given clause
/v1/{complianceCheckUID}/{entityId} GET

Retrieves feedback on a given entity

Security

authService

Type: bearer
Description:

A bearer token to identify the connecting service as an authorizied software tool accredited to provide compliance data

authUser

Type: bearer
Description:

A bearer token to identify the connecting user. Acquired from the OAUTH2 Security Service related to this service.

Paths

Retrieves the basic metadata about the Rule Engine

GET /v1/

Retrieves the basic metadata about the Rule Engine

Uses default content-types: application/json application/xml

200 OK

Returns basic metadata about the Rule Engine. Equivalent XML Response is returned if content type is set appropriately.

ServerIdentity
Initialises a compliance check

PUT /v1/

Initialises a compliance check

Uses default content-types: application/json application/xml

InitialisationData

Uses default content-types: application/json application/xml

200 OK

Returns a GUID for the compliance check

complianceId: string
Returns an overview of the project entities that the rule engine is aware of and the data required for them

GET /v1/{complianceCheckUID}

Returns an overview of the project entities that the rule engine is aware of and the data required for them
complianceCheckUID

The Unique ID of a given compliance check

 path string

Uses default content-types: application/json application/xml

200 OK

Returns the set of entities and the data required for them

idSet: object[]

The set of IDs the rule engine is currently utilising

IDSet
conditions: string[]

A set of conditions for the approval submitted to the rule engine.

string
approval: string , x ∈ { Pending , Approved , Rejected }

The overall approval status of this application

log: string[]

A set of logs describing the process of this application.

string
messages: string[]

A set of messages lodges about this application.

string
securityServiceType: string

The type of authorisation/authentication service used by this rule engine

securityServiceURI: string

The URL of the OAUTH2 security service utilised by this rule engine
authUser
authService
Updates the ID Set used within the Rule Engine

POST /v1/{complianceCheckUID}

Updates the ID used within the Rule Engine

Uses default content-types: application/json application/xml

ids: string[]

A list of entity IDs available on the connecting data source.

string
complianceCheckUID

The Unique ID of a given compliance check

 path string

Uses default content-types: application/json application/xml

200 OK
success: boolean
authUser
authService
Enables the submission of answers to compliance questions to the rule engine

POST /v1/{complianceCheckUID}/answers

Enables the submission of answers to compliance questions to the rule engine

Uses default content-types: application/json application/xml

answers: object[]

A set of answers submitted to the rule engine.

Answer
complianceCheckUID

The Unique ID of a given compliance check

 path string

Uses default content-types: application/json application/xml

200 OK
success: boolean
authUser
authService
Enables the signalling of approval (or not) and the transmission of associated conditions with an approval to the rule engine for onward transmission to the result service.

POST /v1/{complianceCheckUID}/approval

Enables the signalling of approval (or not) and the transmission of associated conditions with an approval to the rule engine for onward transmission to the result service.

Uses default content-types: application/json application/xml

conditions: string[]

A set of conditions for the approval submitted to the rule engine.

string
approval: string , x ∈ { Pending , Approved , Rejected }

The overall approval status of this application (if changed)
complianceCheckUID

The Unique ID of a given compliance check

 path string

Uses default content-types: application/json application/xml

200 OK
success: boolean
authUser
Enables the retrieval of a BCF File documenting any issues identified by the rule engine as part of the checking process

GET /v1/{complianceCheckUID}/bcf

Enables the retrieval of a BCF File documenting any issues identified by the rule engine as part of the checking process
complianceCheckUID

The Unique ID of a given compliance check

 path string

application/zip

200 OK

Returns a BCFzip File as described here
authUser
Enables the submission of compliance data to the rule engine to the implementing service.

POST /v1/{complianceCheckUID}/data

Enables the submission of compliance data to the rule engine to the implementing service.

Uses default content-types: application/json application/xml

dataItems: object[]

A set of data submitted to the rule engine.

DataItem
complianceCheckUID

The Unique ID of a given compliance check

 path string

Uses default content-types: application/json application/xml

200 OK
success: boolean
authUser
authService
Enables the sending of a message to the other parties in the compliance checking process

PUT /v1/{complianceCheckUID}/messaging

Enables the sending of a message to the other parties in the compliance checking process

Uses default content-types: application/json application/xml

message: string

The message to send.
complianceCheckUID

The Unique ID of a given compliance check

 path string

Uses default content-types: application/json application/xml

200 OK
success: boolean
authUser
Returns a list of all compliance results from a given compliance check

GET /v1/{complianceCheckUID}/results

Returns a list of all compliance results from a given compliance check
complianceCheckUID

The Unique ID of the compliance check being considered

 path string
start

The Start Date/Time to query

 query string (date-time)
end

The End Date/Time to query

 query string (date-time)
search

A free text search field to search results

 query string

Uses default content-types: application/json application/xml

200 OK

Returns a list of Compliance Results. Equivalent XML Response is returned if content type is set appropriately.

results: object[]
ComplianceResultDataItem
authUser
Enables the submission of compliance results to the rule engine. This is used for the manual specification of top level results where automated computation is not possible

POST /v1/{complianceCheckUID}/results

Enables the submission of compliance results to the rule engine. This is used for the manual specification of top level results where automated computation is not possible

Uses default content-types: application/json application/xml

dataItems: object[]

A set of results submitted to the rule engine.

ComplianceResultSubmission
complianceCheckUID

The Unique ID of a given compliance check

 path string

Uses default content-types: application/json application/xml

200 OK
success: boolean
authUser
Retrieves feedback on a given clause

GET /v1/{complianceCheckUID}/{clauseId}

Retrieves feedback on a given clause
complianceCheckUID

The Unique ID of a given compliance check

 path string
clauseId

The unique ID of the clause§ about which feedback is requested.

 path string

Uses default content-types: application/json application/xml

200 OK

returns a set of feedback on the request element/clause

entities: string[]

A set of entity IDs that have results applicable to this clause

string
complianceResults: object[][]

A set of compliance results grouped by entities (as per the order in in the entities field)

object[]
ComplianceResultDataItem
authUser
authService
Retrieves feedback on a given entity

GET /v1/{complianceCheckUID}/{entityId}

Retrieves feedback on a given entity
complianceCheckUID

The Unique ID of a given compliance check

 path string
entityId

The unique ID of the entity about which feedback is requested.

 path string

Uses default content-types: application/json application/xml

200 OK

returns a set of feedback on the request element/clause

properties: string[]

The list of properties of the give entity that have compliance results

string
complianceResults: object[][]

A set of compliance results for this entity grouped by properties (as per the order in in the properties field)

object[]
ComplianceResultDataItem
authUser
authService

Schema definitions

Answer: object

Represents an answer to questions posed by the rule engine

propertyId: string

The id of the property being answered

id: string

The Entity ID to which this answer is relevant

answer: object , x ∈ { true , false , unknown }

The actual answer

missValue: string

The optional miss value. This is an indication, if the answer is false, how far out of tolerance the value is.

supportingFileData: string

The BASE64 Encoded File Data that supports/evidences this answer

supportingFileContentType: string

The MIME Content Type of the Support file data (if present)

ComplianceResultDataItem: object

Represents an individual result from a compliance check

reference: string

Either the clause reference or the property reference depending on the context the reuslt is retrieved

time: string (date-time)

The date/time that this result was generated

reasons: string[]

A set of reasons why this result has been computed this includes information on what data items have been used, what software tools produced this results, if the result was automatically or human generated etc...

string
attributation: string

A string describing what/who generated this result

result: string , x ∈ { true , false }

The result that has been computed

supportingFileData: string[]

The BASE64 Encoded File Data that supports/evidences this answer

string
supportingFileContentType: string[]

The MIME Content Type of the Support file data (if present)

string

ComplianceResultSubmission: object

The Submission of a result of a clause

complianceDocumentReference: string

The URI of the clause within a compliance document that this result is generated from

reasons: string[]

A set of reasons why this result has been computed this includes information on what data items have been used, what software tools produced this results, if the result was automatically or human generated etc...

string
result: string , x ∈ { true , false }

The result that has been computed

supportingFileData: string

The BASE64 Encoded File Data that supports/evidences this answer

supportingFileContentType: string

The MIME Content Type of the Support file data (if present)

DataItem: object

Represents a data item returned in response to requests from the rule engine

propertyId: string

The id of the property being answered

id: string

The Entity ID to which this data item is relevant

data: string

The data item being returned

IDSet: object

Represents a set of entity IDs and their associated metadata

id: string

The entity ID

type: string

The type of the object

friendlyName: string

A friendly name to represent the object

keyVariables: string[]

A list of key data items for this entity that the rule engine thinks the connecting data source needs to be aware of in order to contextualise itself

string
requiredData: object[]

A list of data required by the rule engine about this entity. This can either be a request for data or a request to answer a question

object
id: string

An ID of this data item to be used when sending its result back to the rule engine

propertyName: string

The name of the property that we wish to retrieve

unit: string

The unit requested - defaults to unitless if absent

complianceDocumentReference: string

The URI of the clause within a compliance document that this result is generated from

Individual: object

The Information Related to an individual named on a building regulations application

title: string

The individuals title.

name: string

The individual's name

companyname: string

The individual's company name

email: string

The individual's email address

address: string

The individual's address

postcode: string

The individual's postcode

telephone: string

The individual's telephone number

fax: string

The individual's fax number

mobile: string

The individual's mobile phone number

position: string , x ∈ { agent , applicant }

The individual's position in the application

InitialisationData: object

Represents a set of metadata to initialise the compliance check

operationMode: string , x ∈ { precheck , forassessment }
lifecyclestage: string

The project lifecycle stage of this check. Taken from the RIBA2020/CIC plan of work - here.

projectSecurityServiceType: string

The type of authorisation/authentication service used by this project

projectSecurityServiceURI: string

The URL of the OAUTH2 security service utilised by this project

complianceDocumentReference: string[]

The URI of the clause within a compliance document that is used for this compliance check

string
modelServerType: string

A textual identifcation of the type of model server being utilised.

modelServerURL: string

A URI to access a model on a model server. This is passed to building control to allow model access.

UPRN: string

The UPRN of the building being considered - as described here

regulatorIdentification: string

A reference to the regulatory body that should assess this check, or blank if it is not for external assessment

individuals: object[]

A set of individuals involved in the compliance check

Individual
address: string

The address where the work is to be carried out

postcode: string

The postcode where the work is to be carried out

description: string

A full description of the work

presentUse: string

The present use of the building

proposedUse: string

The proposed use of the building

fireSafetyOrder: boolean

In scope of Regulatory Reform (Fire Safety) Order 2005

consentToExtension: boolean

Does applicant consent to extension of proscribed period

consentToConditions: boolean

Does applicant consent to conditions being applied

electricalSafetyConfirmation: boolean

Will any electrical installation work be designed, constructed, inspected and tested in accordance with BS7671 or will it be undertaken by an electrician registered with a competent persons scheme?

ServerIdentity: object

Represents the basic metadata of the rule engine

name: string

The name of this rule engine

description: string

The description of this rule engine

operator: string

The name of the organisation operating this rule engine