The beCPG REST API SDK includes a set of APIs and samples that allows developers to quickly build
out-of-process Java applications that integrate with beCPG.
This SDK provides functionality to consume beCPG REST Remote API.
| Version | beCPG Version | Version API | Version JAVA | Changes |
|---|---|---|---|---|
| 1.1.18 | >= 23.4.2 | >= 3.5 | JAVA 17 | Read a d:date published as a calendar day, keeping the instant form of earlier repositories; provide the reactive OAuth2 client registration repository in servlet applications; bump Spring Boot to 3.5.16 (CVE-2026-22732) |
| 1.1.17 | >= 23.4.2 | >= 3.5 | JAVA 17 | Add ingList field definitions |
| 1.1.16 | >= 23.4.2 | >= 3.5 | JAVA 17 | Add configurable HTTP connect/response timeouts; reduce Keycloak load (cache out-of-session alf_ticket, refresh tokens); fix OAuth2 conditional activation |
| 1.1.15 | >= 23.4.2 | >= 3.5 | JAVA 17 | Add ProjectAPIModel, person properties and validation constraints |
| 1.1.14 | >= 23.4.2 | >= 3.5 | JAVA 17 | Add secure batch endpoints in ChannelAPI |
| 1.1.13 | >= 23.4.2 | >= 3.5 | JAVA 17 | Add bcpg:allergenListQtyPerc field constant |
| 1.1.12 | >= 23.4.2 | >= 3.5 | JAVA 17 | Fix alf ticket encoding |
| 1.1.11 | >= 23.4.2 | >= 3.5 | JAVA 17 | Bug fix oauth |
| 1.1.10 | >= 23.4.2 | >= 3.5 | JAVA 17 | Add alfTocken session in basic Auth |
| 1.1.9 | >= 23.4.2 | >= 3.5 | JAVA 17 | Add common helper functions |
| 1.1.8 | >= 23.4.2 | >= 3.5 | JAVA 17 | Add BecpgAPIModel, setAssociations helpers, HTTP/1.1 and TLSv1.2 forcing options |
| 1.1.7 | >= 23.4.2 | >= 3.5 (Partial support on >=3.3) | JAVA 17 | Bug fixes |
| 1.1.6 | >= 23.4.2 | >= 3.5 (Partial support on >=3.3) | JAVA 17 | Add advanced search support |
| 1.1.5 | >= 4.2.3 | >= 3.5 (Partial support on >=3.3) | JAVA 17 | Fix cm:person charact and single assoc |
| 1.1.4 | >= 4.2.3 | >= 3.5 (Partial support on >=3.3) | JAVA 17 | Fix Memory issue |
| 1.1.3 | >= 4.2.3 | >= 3.5 (Partial support on >=3.3) | JAVA 17 | Bugfix in compressParam |
| 1.1.2 | >= 4.2.3 | >= 3.5 (Partial support on >=3.3) | JAVA 17 | Add entity schema support |
| 1.1.1 | >= 4.2.2 | >= 3.4 (Partial support on >=3.3) | JAVA 17 | Add nested datalist getter (API >=3.4) |
| 1.1.0 | >= 4.2.2 | >= 3.3 (Partial support on >=3.1) | JAVA 17 | Migrate To spring boot 3 and Java 17 |
| 1.0.1 | >= 4.2.2 | >= 3.3 (Partial support on >=3.1) | JAVA 11 | Minor fix |
| 1.0.0 | >= 4.2.2 | >= 3.3 (Partial support on >=3.1) | JAVA 11 | Remote API support |
beCPG REST API SDK consist of the following libraries:
- becpg-java-rest-api: Allows applications to consume beCPG public REST APIs.
- Java version 17 or higher
- Maven version 3.3 or higher
Maven:
First, add to the repositories the beCPG public repository containing the artifacts:
<repositories>
<repository>
<id>becpg-registry</id>
<url>artifactregistry://europe-west1-maven.pkg.dev/becpg-314807/becpg-mvn</url>
</repository>
</repositories>Then, add the dependency on the desired starter(s)
<dependencies>
<!-- Java REST API -->
<dependency>
<groupId>fr.becpg</groupId>
<artifactId>becpg-java-rest-api</artifactId>
<version>1.1.18</version>
</dependency>
</dependencies>In your application.properties file provide URL, authentication mechanism and credentials for
accessing the REST API:
content.service.url=http://repository:8080
content.service.security.basicAuth.username=admin
content.service.security.basicAuth.password=admin
If you are using OAuth2, you can use client-credential based authentication:
spring.security.oauth2.client.registration.becpg-java-rest-api.provider=becpg-ids
spring.security.oauth2.client.registration.becpg-java-rest-api.client-id=clientId
spring.security.oauth2.client.registration.becpg-java-rest-api.client-secret=clientSecret
spring.security.oauth2.client.registration.becpg-java-rest-api.authorization-grant-type=client_credentials
spring.security.oauth2.client.provider.becpg-ids.token-uri=${keycloak.auth-server-url}/auth/realms/${keycloak.realm}/protocol/openid-connect/token
Or OAuth2 password based authentication:
spring.security.oauth2.client.registration.becpg-java-rest-api.provider=becpg-ids
spring.security.oauth2.client.registration.becpg-java-rest-api.client-id=clientId
spring.security.oauth2.client.registration.becpg-java-rest-api.client-secret=clientSecret
spring.security.oauth2.client.registration.becpg-java-rest-api.username=username
spring.security.oauth2.client.registration.becpg-java-rest-api.password=pwd
spring.security.oauth2.client.registration.becpg-java-rest-api.authorization-grant-type=password
spring.security.oauth2.client.provider.becpg-ids.token-uri=${keycloak.auth-server-url}/auth/realms/${keycloak.realm}/protocol/openid-connect/token
You can also use or combine with custom header authentication
content.service.headers={'x-restricted-custom':'XXXXXX'}
Finally, if you want to provide a custom authentication mechanism, you can enable the delegated external authentication:
content.service.security.delegated=true
And provide a bean that implements the interface DelegatedAuthenticationProvider.
When OAuth2 is enabled, the SDK reuses the bearer token during a doInSession(...) scope and only reacquires a token on 401 responses.
Behavior:
- Avoids token acquisition on every request inside a connector job/session.
- Automatically retries authentication when the token is expired or rejected (HTTP 401).
- Applies to OAuth2 modes (
client_credentialsandpassword).
When Basic authentication is enabled, the SDK can reuse an Alfresco ticket in a doInSession(...) scope:
- The first call performs an Alfresco login (
/alfresco/service/api/login) using configured Basic credentials. - The returned
alf_ticketis reused for subsequent requests in the same scope. - On
401, the SDK refreshes the ticket and retries the request once. - Outside
doInSession(...), the SDK keeps direct Basic authentication on each request.
It is possible to disable SSL verification with the option (For testing only for security reasons):
remote.ssl.trustAll=true
If the target server has issues with HTTP/2 or TLS negotiation, you can force HTTP/1.1 or TLSv1.2:
remote.force.http1=true
remote.force.tls12=true
If fields param reach the connector max request size limit its possible to compress header:
remote.compress.param=true
The underlying reactive HTTP client (reactor-netty) is bounded by two timeouts so that a dropped or half-open connection (e.g. an unstable WAN/satellite link) makes the call fail fast instead of blocking the caller indefinitely — all API methods block on the response:
# Max time (ms) to establish the TCP connection. 0 disables the bound. Default: 30000
remote.connect.timeout=30000
# Max time (s) to fully receive a response once the request is sent. A timeout raises a
# ReadTimeoutException instead of hanging forever. 0 disables the bound. Default: 300
remote.response.timeout=300
A property carries a date in one of two shapes, and RemoteNodeInfo.getDateProp(...) reads both, so
one build of your application works against the whole range of supported repositories:
- a
d:datetimeis a point in time, published as a UTC instant —2026-02-27T18:23:25.906Z; - a
d:dateis a calendar day. beCPG 26.1 and above publish it as a plain day —2027-07-01. Earlier versions published the instant that day happens to be stored at, which reads as the previous day whenever the repository runs ahead of UTC.
A plain day is anchored at midnight in the time zone of the JVM that reads it, so formatting it back out yields the same day whatever that time zone is. An instant keeps its own meaning: rendering it is still subject to the time zone you render it in.
DateExtractorHelper.isDate(...) tells both shapes apart from anything else, and
DateExtractorHelper.parse(...) turns either into a java.util.Date. A value isDate rejects is
left as text, which is what you want for a property that merely looks like a date.
@Autowired
private EntityApi entityApi;
@Test
void testEntityApi() {
List<RemoteEntityRef> entities = entityApi.list("+TYPE:\"bcpg:finishedProduct\" AND +bcpg\\:erpCode:\"PERF-PF1\"");
for(RemoteEntityRef entityRef : entities) {
RemoteEntity entity = entityApi.get(entityRef.getEntity().getId());
Assert.assertNotNull(entity.getName());
Assert.assertNotNull(entity.getAttributes());
Assert.assertNotNull(entity.getDatalists());
logger.info(entity.getAttributes().get("bcpg:entityTplRef").toString());
List<RemoteNodeInfo> geoOrigins = entity.getAssociations("bcpg:productGeoOrigin");
RemoteNodeInfo entityTpl = entity.getAssociation("bcpg:entityTplRef");
break;
}
This is the documentation for the EntityAPI interface.
Lists the entities that match the given query.
query: a string representing the query to execute.
A list of RemoteEntityRef objects representing the entities that match the given query.
Lists the entities that match the given query.
query: a string representing the query to execute.attributes: a list of strings representing the attributes to include in the response.maxResults: an integer representing the maximum number of results to return.
A list of RemoteEntityRef objects representing the entities that match the given query.
List<RemoteEntityRef> list(String query, List<String> attributes, int maxResults, Map<String, Boolean> params)
Lists the entities that match the given query.
query: a string representing the query to execute.attributes: a list of strings representing the attributes to include in the response.maxResults: an integer representing the maximum number of results to return.params: a map of strings to booleans representing the parameters to pass to the API (e.g., "appendCode", "appendErpCode", etc.).
A list of RemoteEntityRef objects representing the entities that match the given query.
Retrieves the specified entity.
id: a string representing the ID of the entity.
A RemoteEntity object representing the entity with the specified ID.
RemoteEntity get(String id, List<String> attributes, List<String> datalists, Map<String, Boolean> params)
Retrieves the specified entity.
The "attributes" and "datalists" parameters can be used to filter the response and reduce its size. There are three types of filtering available:
- Property filtering: only includes the listed properties (e.g. "fields=bcpg:legalName")
- Association filtering: only includes the listed associations (e.g. "fields=bcpg:clients")
- List filtering: only includes the listed lists (e.g. "lists=bcpg:compoList")
You can also extract properties of an association by specifying the association name and its properties in the "fields" parameter, using the following format: "ASSOC_Name1|PROP_Name1,ASSOC_Name1|PROP_Name2".
The negative form is also supported (available in version 3.1 and above):
- "lists=!bcpg:activityList"
- "fields=!cm:created,!bcpg:nutListRoundedValue,!cm:modifier,!cm:creator,!cm:modifier,!cm:modified,!bcpg:entityScore,!bcpg:formulatedDate,!bcpg:illLogValue"
The "params" parameter allows you to pass certain parameters to the API (available in version 3.1 and above):
- "appendCode" (true): disables the addition of the beCPG code
- "appendErpCode" (true): disables the addition of the ERP code
- "appendMlTextConstraint" (true): disables the addition of multilingual constraints
- "appendNodeRef" (true): disables the addition of the node ID
- "appendDataListNodeRef" (true): disables the addition of the node ID for data list nodes
- "appendContent" (false): enables the inclusion of file content in the JSON response
id: a string representing the ID of the entity.attributes: a list of strings representing the attributes to include in the response.datalists: a list of strings representing the data lists to include in the response.params: a map of strings to booleans representing the parameters to pass to the API.
A RemoteEntity object representing the entity with the specified ID.
Checks if an entity with the given ID exists.
id: a string representing the ID of the entity.
A string representing the result of the check. The string will be "OK" if the entity exists, and "KO" if it does not.
Updates the specified entity.
entity: aRemoteEntityobject representing the entity to update.
A RemoteEntity object representing the updated entity.
The ChannelAPI interface provides methods for accessing and manipulating channels.
Lists the entities in the specified channel.
channelId: a string representing the ID of the channel.
- a list of
RemoteEntityRefobjects representing the entities in the channel.
Lists the entities in the specified channel, including the specified attributes.
channelId: a string representing the ID of the channel.attributes: a list of strings representing the attributes to include in the list.maxResults: an integer representing the maximum number of results to return.
- a list of
RemoteEntityRefobjects representing the entities in the channel.
Gets the specified channel.
channelId: a string representing the ID of the channel.
- a
RemoteEntityobject representing the channel.
Starts a batch for the specified channel.
channelId: a string representing the ID of the channel.batchId: a string representing the ID of the batch.
- a
RemoteAPIResponseobject representing the response of the remote API.
Updates the channel status on an entity within a batch.
channelId: a string representing the ID of the channel.nodeRef: a string representing the NodeRef of the entity.attributes: a map of strings to objects representing the attributes to update.
- a
RemoteAPIResponseobject representing the response of the remote API.
Ends the batch for the specified channel.
channelId: a string representing the ID of the channel.attributes: a map of strings to objects representing the channel attributes to update at the end of the batch.
- a
RemoteAPIResponseobject representing the response of the remote API.
This interface provides methods for interacting with content in the system.
Gets or creates a shared URL for the given node.
remoteNodeInfo: aRemoteNodeInfoobject representing the node for which to get or create a shared URL.
A string representing the shared URL for the node.
IOException: if there is an error while getting or creating the shared URL.
Writes the content of the given node to the specified file.
remoteNodeInfo: aRemoteNodeInfoobject representing the node whose content to write.destFile: aPathobject representing the file to write the content to.
IOException: if there is an error while writing the content.