The following describes the extensions and deviations of the BCF API v2.1 implementation in OpenProject.
This document should be read as an extension to the standard specification. The user should read the standard specification first, and then take a look at this document to be informed about OpenProject specificities.
While the intent of the implementation is to follow the specification, the API builds on the existing OpenProject data schema and by that requires to map between the concepts required in the much broader domain of project management and BCF.
In other parts, the BCF API specification has not been completely implemented. It will be amended where requirements dictate. OpenProject offers a second API (v3) which might be able to fill the gaps the BCF API implementation still has.
The document follows the structure of the standard specification to ease comparing the two documents.
All end points are nested within the /api
path. So for a server listening on https://foo.com/
the API root will be
https://foo.com/api/bcf/2.1
. For a server listening on https://foo.com/bar
the API root will be
https://foo.com/bar/api/bcf/2.1
.
Not implemented
Implemented
Implemented
Not implemented
Implemented
Implemented
Implemented
Implemented
Authorization is granted based on the view_linked_issues and the manage_bcf permission. As BCFs share part of their data structure with WorkPackages, which enables them to be worked on by the project team just like any other work package, a user also needs to have the view_work_packages permission to have view_linked_issues. For manage_bcf the permissions view_work_packages, add_work_packages, edit_work_packages and delete_work_packages are dependently required.
Implemented
The authorization
field is always returned, regardless of an includeAuthorization
query parameter.
Implemented
The implementation relies on a client to particularly adhere to this.
Implemented
Out of scope
Not implemented
Implemented
The following OAuth2 flows are supported:
authorization_code_grant
- 4.1 - Authorization Code Grantclient_credentials
- 4.4 - Client Credentials Grant
The clients_credentials
grant explicitly ruled out by the standard specification as not being user specific can be supported by OpenProject as the grant is mapped to a user account
when configuring the OAuth access.
Before a client is able to perform the flows, they need to be configured in OpenProject. bcf_v2_1
needs
to be checked for the scope. That value also needs to be provided for the scope property in OAuth requests.
The OAuth2 flows alternatively proposed by the specification
implicit_grant
- 4.2 - Implicit Grantresource_owner_password_credentials_grant
- 4.3 - Resource Owner Password Credentials Grant are not implemented.
Out of scope
Not implemented
Implemented
The project_id
is an integer value. However, the API also understands requests where the project identifier, e.g. bcf_project
is used instead of the integer within a url. So the following urls might point to the same project resource: /api/bcf/2.1/projects/3
and /api/bcf/2.1/projects/bcf_project
.
Partly implemented
The end point is implemented but lacks the authorization
property. However, the Project Extension Service is completely implemented and provides the same information.
Partly implemented
The end point is implemented but lacks the authorization
property. However, the Project Extension Service is completely implemented and provides the same information.
Implemented
Implemented and extended
However, as some end points are not implemented, the actions indicating the ability to call those end points will also not be returned, e.g. updateDocumentReferences
Out of scope
Implemented and extended
- viewTopic - The ability to see topics (see 4.2.3 GET Topic Service)
Implemented
Implemented
BCF topics are tightly coupled to work packages in OpenProject. This coupling is denoted in the reference_links
property
of a topic which will always have a link to the work package resource in the API v3. e.g.:
<-- other properties -->
"reference_links": [
"/api/v3/work_packages/92"
],
<-- other properties -->
Partly implemented
The following properties are not supported:
labels
(the property exists but cannot be written and is always empty)stage
(the property exists but cannot be written and is always null)bim_snippet.snippet_type
bim_snippet.is_external
bim_snippet.reference
bim_snippet.reference_schema
OData sort, filtering and pagination is not supported.
Partly implemented
See 4.2.3 GET Topic Service for details.
Either a new work package is created or, if a work package is referenced in the reference_links
section, a the referenced
work package is associated to the newly created topic. A work package can only be associated to one topic and vice versa.
Partly implemented
See 4.2.3 GET Topic Service for details.
Partly implemented
The reference to the work package cannot be altered.
See 4.2.3 GET Topic Service for details.
Implemented
The associated work package will also be deleted.
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented
Not implemented