The Bulk Check API

Owned by Claudius Hörth
Feb. 08, 2024
4 min read

The Bulk Check API consists of 3 services:

  • BulkCheckService, which provides authentication and document check functionality,
  • BulkCheckAuthenticationService, which provides support for CMS authentication,
  • BulkCheckSettingsService, which provides access to settings.

Congree Bulk Check Service

The Congree Bulk Check Service itself is available via the following address:

http://<BCS host>/CongreeBulkCheckService/BulkCheckService.svc

The interface definition is available on a separate page.

Bulk Check Authentication Service

The Congree Bulk Check Service also supports CMS authentication in addition to Congree authentication. To apply this, CMS authentication should be enabled in the User Management of Congree Control Center.

Bulk Check Authentication service is available via the following address:

http://<BCS host>/CongreeBulkCheckService/BulkCheckAuthenticationService.svc

Interface definition is available on a separate page.

Authentication Service generates security tokens which can be used in the main Bulk Check Service. Since security tokens provided are not protected with the password, it is strongly recommended to communicate with this service over SSL (see Security topic).

At the end of the session, these tokens should be released like ordinary ones – by calling ReleaseSecurityToken method of IBulkCheckService.

Certificates configuration

Two certificates are required to use CMS authentication (with the public key on the Congree Bulk Check Service side and with the private key on the client side). 
The following steps show example how to create and configure certificates.

  1. It is necessary to install Windows SDK (https://developer.microsoft.com/en-us/windows/downloads/windows-8-1-sdk) if it is not installed.
    1. (Or just provide these two files, if you do not want to download and install an over 1 Gb package...: makecert_pvk2pfx.zip)
  2. Run the following cmd to generate root certificate:
    1. makecert -sv CongreeBulkCheckRoot.pvk -n "CN=CongreeBulkCheckRoot" CongreeBulkCheckRoot.cer -r
      1. You are prompted to set the secret password of the root certificate.
      2. You are prompted to enter this secret password to generate the pvk-file
    2. and install output file in Trusted Root Certificate Authorities of the Local Machine (see SSL configuration above)  where Congree Bulk Check Service is installed.
  3. As next step private client certificate should be generated. Note that private key is protected with the password.
    If you are going to use this private key to configure Java clients note that Java password for store and private key password should be identical and by default it is "changeit" - so for testing purpose the same password should be used during the following command:
    1. makecert -n "CN=CongreeBulkCheckClient" -ic "CongreeBulkCheckRoot.cer" -iv "CongreeBulkCheckRoot.pvk" -a sha1 -sky exchange -sv "CongreeBulkCheckClient.pvk" "CongreeBulkCheckClient.cer"
      1. You are prompted to set the secret password of the client certificate
      2. You are prompted to enter this secret password of the client certificate
      3. You are prompted to enter the secret password of the root certificate
    2. pvk2pfx -pvk "CongreeBulkCheckClient.pvk" -spc "CongreeBulkCheckClient.cer" -pfx "CongreeBulkCheckClient.pfx" -pi ###desiredpw###
      1. You are prompted to enter the secret password of the client certificate

  4. Result CongreeBulkCheckClient.pfx file should imported in Personal Certificates of each client machine. On the client machine also should be imported CongreeBulkCheckRoot.cer in Trusted Root Certificate Authorities as described in #2.

Configuration for Java clients

  1. To add CongreeBulkCheckRoot.cer to the Java trust store, run the following command from JRE installation folder:
    1. keytool -import -alias BulkCheckRoot -file CongreeBulkCheckRoot.cer -keystore "c:\Program Files (x86)\Java\jre1.8.0_66\lib\security\cacerts"
  2. To add client certificate to Java key store, run the following command:
    1. keytool -importkeystore -srckeystore CongreeBulkCheckClient.pfx -srcstoretype pkcs12 -destkeystore "c:\Program Files (x86)\Java\jre1.8.0_66\lib\security\cacerts" -deststoretype JKS

    2. Note that in this case password of key store and private key in the certificate (.pfx) should be identical. To change password the following commands should be used:

      1. To find private key alias name:
        1. keytool -list -v -keystore "c:\Program Files (x86)\Java\jre1.8.0_66\lib\security\cacerts" -storepass changeit
      2. keytool -keypasswd -alias  -keystore "c:\Program Files (x86)\Java\jre1.8.0_66\lib\security\cacerts 
        1. where is alias name found after first line was executed.

Bulk Check Settings Service

The Bulk Check Settings Service is available via the following address:

http://<BCS host>/CongreeBulkCheckService/BulkCheckSettingsService.svc

The interface definition is available on a separate page.

The service provides current Document Check settings etc.

Examples

Here is a small Java code snippet which shows how to use Congree Bulk Check Service.

Java example code 
//Configure URL to the Congree Bulk Check Service
String address = "http://localhost/CongreeBulkCheckService/BulkCheckService.svc";
//Set up Congree user name
String username = "default";
//Set up document rule set name
String ruleset = "Congree Standard";
//Input XML to be checked
String xml = "<p>Herzlichen Glückwunsch, dass Sie sich für das ContentGrasp SX Headset entschieden haben.</p>";
 
 
BulkCheckServiceLocator locator = new BulkCheckServiceLocator();
locator.setEndpointAddress("BasicHttpBinding_IBulkCheckService", address);
IBulkCheckService service = locator.getBasicHttpBinding_IBulkCheckService();
 
//Request security token before start checking
String securityToken = service.createSecurityToken(username, "");
 
 
LinguisticCheckResult checkResult = service.checkDocument(securityToken, xml, ruleset);
System.out.println("Checked. Result is " + checkResult.getResultXml());
 
//After check document security token should be released. Otherwise license will stay locked.
service.releaseSecurityToken(securityToken)

The resulting XML will look like the following example:

Sample output 
<p>Herzlichen Glückwunsch, dass Sie sich für das <?cngr-lc-b 0?>ContentGrasp SX<?cngr-lc-e 0?> Headset entschieden haben.</p>

In the result XML file, every found error is marked with

 Command line sample to call attached JAR:

java -jar WebServiceClientSample.jar localhost "default" "" "Congree Standard" "<p>text content to be checked</p>" false false ""

Command line sample to use sample with SSL protection:

java -jar WebServiceClientSample.jar localhost "default" "" "Congree Standard" "<p>text content to be checked</p>" false true "c:\Program Files (x86)\Java\jre1.8.0_66\lib\security\cacerts"

Command line sample to use sample with CMS authentication:

java -jar WebServiceClientSample.jar localhost "JavaCMS" "" "Congree Standard" "<p>text content to be checked</p>" true true "c:\Program Files (x86)\Java\jre1.8.0_66\lib\security\cacerts"

 

Note that Java certificate store password is hardcoded in the sample and it is "changeit" (default password for Java store).

The following parameters are available:

  • Congree Bulk Check Service host name
  • Congree user or CMS name
  • Congree user password. In case of CMS it should be empty
  • Congree document-specific rule set 
  • XML to check
  • Use CMS authentication
  • Use SSL connection
  • JRE certificate store (e.g. "c:\Program Files (x86)\Java\jre1.8.0_66\lib\security\cacerts"). Note that if SSL connection or CMS authentication is selected this parameter must be specified