WEB/REST services

As standard, beCPG offers an HTTP REST service called Remote API which allows:

• import entity data in XML format,
• to export the data of an entity in XML format according to criteria (Ex: I wish all the products which are validated and effective on the date DD/MM/YYYY).

This REST service makes it possible to create interfaces with third-party software such as ERP. By entity, we mean the product, the customer, the supplier, the project, etc... with all of its information and this in a dynamic way without development.

The exchange interface can therefore be implemented by a third-party tool whose role is to:

• managing exchanges,
• transform flows (transformation rules on lists of values for example),
• handle errors. This third-party tool dialogues with the Remote API to import and export beCPG data. 2 approaches are possible:
• the client has a third-party tool to create the interface,
• the client wants beCPG to set up a third-party tool to create the interface. In addition, all the application's APIs are accessible via REST services:
• CRUD, Create/Read/Update/Delete operations
• wording
• documentary generation
• recovery of versions, technical sheets
• etc...

Versions

Different versions of the APIs exist depending on your version of beCPG. Backward compatibility is maintained. The XML format for example is identical between version 1 and 3.1.

The table below lists the different versions of the API and the main changes

Below are the associated beCPG versions

The options specific to each version of the API are noted [>= 3.1] in the documentation

beCPG API

The beCPG remote API offers the following REST URLs:

From version 1

<url>/becpg/remote/entity/list?path={path}</url>
<url>/becpg/remote/entity/list?query={query}&maxResults={maxResults}</url>
<url>/becpg/remote/entity?nodeRef={nodeRef}</url>
<url>/becpg/remote/entity?path={path}</url>
<url>/becpg/remote/entity?query={query}</url>

From version 2.1

<url>/becpg/remote/formulate?nodeRef={nodeRef}</url>
<url>/becpg/remote/formulate?path={path}</url>
<url>/becpg/remote/formulate?query={query}</url>
<url>/becpg/remote/merge?nodeRef={nodeRef}</url>
<url>/becpg/remote/check?nodeRef={nodeRef}</url>
<url>/becpg/remote/content?nodeRef={nodeRef}</url>
<url>/becpg/remote/branch?nodeRef={nodeRef}</url>
<url>/becpg/remote/report?nodeRef={nodeRef}&tplNodeRef={tplNodeRef}</url>
<url>/becpg/remote/report?nodeRef={nodeRef}&tplNodeRef={tplNodeRef}&locale={locale}</url>
<url>/becpg/remote/report?nodeRef={nodeRef}&tplNodeRef={tplNodeRef}&locale={locale}&format={format}</url>

The POST/GET/PUT/DELETE methods allow respectively to add, find, update and delete entities in the PLM (product, customer, supplier, etc ..).

List entities

The list of entities is obtained with the LIST query and can be filtered according to advanced search criteria (last product modified since a specified date for example).

<url>/becpg/remote/entity/list?path={path}</url>
<url>/becpg/remote/entity/list?query={query}&maxResults={maxResults}&fields={fields}</url>
<url>/becpg/remote/entity/list?path={path}&maxResults={maxResults}&fields={fields}</url>

The search syntax is the Alfresco FTS ¹ syntax: https://docs.alfresco.com/search-services/latest/using/

¹. You can also refer to the Lucene Query Building part of the documentation ↩

Attention depending on the syntax used, the search may have a lag of a few minutes with the modifications made on the system. This time is related to indexing. To avoid this it is advisable to use only searches using the db-afts syntax. If this is not the case, it is necessary to shift the criteria of rec walk of 10 min. To test that your query is db-afts compatible, use the node browser choosing db-afts, your search should return results.

Transactional search (db-afts) supports the following criteria:

• PARENT
• TYPE
• ASPECT
• EXACTTYPE
• EXACTASPECT -= (Property equality)
• Date Range
• AND NOT OR

More information on transactional searches:

https://docs.alfresco.com/search-services/latest/config/transactional/

An example of a request allowing to have a finished product according to its erp-code:

 +TYPE:"bcpg:finishedProduct" AND =@bcpg\\:erpCode:"codeErp" AND -ASPECT:"bcpg:compositeVersion"
 (-ASPECT:"bcpg:compositeVersion" excludes older versions)

The corresponding URL:

http://localhost:8080/alfresco/service/becpg/remote/entity?query=%2BTYPE%3A%22bcpg%3AfinishedProduct%22%20AND%20%2B%40bcpg%5C%3AerpCode%3A%22codeErp%22%20AND %20-ASPECT%3A%22bcpg%3AcompositeVersion%22

To get the encoded url (in firefox console):

 encodeURIComponent('+TYPE:"bcpg:finishedProduct" AND =@bcpg\\:erpCode:"codeErp" AND -ASPECT:"bcpg:compositeVersion"')

The maxResults parameter allows you to specify a number of results (-1 to have all the results)

The format parameter is used to modify the XML format of the response

• format=xml (Default)
• format=json (Format json)

The fields parameter allows to specify fields or associations to extract in the results [>2.0]:

http://localhost/alfresco/service/becpg/remote/entity/list?query=%2BTYPE%3A%22bcpg%3AfinishedProduct%22&fields=bcpg:legalName,bcpg:clients

Examples:

Sample bash script to directly retrieve in the form of an xml file a list of entities:

#!/bin/sh

export REMOTE_SERVER=http://localhost:8080/alfresco/service/becpg/remote/entity
export REMOTE_USER=admin
echo "Enter password"
read REMOTE_PASSWORD=

#Retrieve the list of nodes:

wget --quiet --http-user=$REMOTE_USER --http-password=$REMOTE_PASSWORD --header=Accept-Charset:iso-8859-1,utf-8 --header=Accept-Language:en-us -O list.xml $REMOTE_SERVER/list
count=1

#We go through the list
while [ -n "$nodeRef" -o $count = 1 ]
    do
       nodeRef=`cat list.xml | xpath -q -e //*[$count]/@nodeRef | sed s/nodeRef=//g |sed s/\"//g`
       echo "Getting node $nodeRef";
       # We save each node
       wget --quiet --http-user=$REMOTE_USER --http-password=$REMOTE_PASSWORD --header=Accept-Charset:iso-8859-1,utf-8 --header=Accept-Language:en-us -O entity_$count.xml $REMOTE_SERVER?nodeRef=$nodeRef
       count=$((count+1))
done

Get entity

For getting entities, two REST services are available:

The remote API using the following TYPE GET requests

<url>/becpg/remote/entity?nodeRef={nodeRef}&format={format}</url>
  <url>/becpg/remote/entity?path={path}&format={format}</url>
  <url>/becpg/remote/entity?query={query}&format={format}</url>
  <url>/becpg/remote/entity?nodRef={nodeRef}&lists={lists}&fields={fields}</url>
  <url>/becpg/remote/entity?path={path}&lists={lists}&fields={fields}</url>
  <url>/becpg/remote/entity?query={query}&lists={lists}&fields={fields}</url>

A 404 error will be returned if no entity is found with the provided parameters.

The format parameter is used to modify the XML format of the response:

• format=xml (Default)
• format=json (Format json)) [>= 3.0]
• format=json_schema (JSON Validation Schema) [>= 4.2.1]
• format=xml_all (Contains the details of all associations)
• format=xml_excel (Format suitable for use as datasource in excel)
• format=xml_light (This format does not contain child type associations)
• format=xsd (This format allows to extract the XSD)
• format=xsd_excel (This format allows to extract the XSD for excel)

additional filter parameters to lighten the response. There are 3 types of filtering [>=2.0]:

• Properties filtering: include only listed properties (fields=bcpg:legalName)
• Association filtering: only includes listed associations (fields=bcpg:clients)
• Lists filtering: include only listed lists (lists=bcpg:compoList)

In addition, you can extract the properties of an association by passing in the fields parameter the name of the associations and their properties, respecting the following format: ASSOC_Name1|PROP_Name1,ASSOC_Name1|PROP_Name2.

The negative form is also supported [>=3.1]:

• lists=!bcpg:activityList
• fields=!cm:created,!bcpg:nutListRoundedValue,!cm:modifier,!cm:creator,!cm:modifier,!cm:modified,!bcpg:entityScore,!bcpg:formulatedDate,!bcpg:illLogValue

Finally, for the JSON format, the params parameter allows certain parameters to be passed to the API [>=3.1]:

• appendCode (true): Disables the addition of the beCPG code
• appendErpCode (true): Disables the addition of ERP code
• appendMlTextConstraint (true): Disables the addition of constraints in multilingual
• appendNodeRef (true): Disables the addition of the ID
• appendMlText (true): Disables the addition of values in multilingual [>=3.2]
• appendContent (false): Allows to include the contents of the files in the JSON

This parameter is in JSON format

params = {
         "appendCode": true,
         "appendErpCode": false
         }

And must be encoded in the request

params=%7B%22appendCode%22%3Afalse%2C%22appendMlTextConstraint%22%3Afalse%2C%22appendContent%22%3Atrue%7D

It is also possible to specify parameters in the URL using jsonParam as a prefix [>=3.3]

?jsonParamAppendCode=true&jsonParamAppendErpCode=false...

Example:

http://localhost/alfresco/service/becpg/remote/entity?nodeRef=workspace://SpacesStore/9b4dd09a-afaa-41ec-84eb-db062146975c&fields=bcpg:legalName,bcpg:clients,bcpg:compoListProduct|bcpg:productState&lists= bcpg:compoList

Get insights via report API

<url>/becpg/report/datasource?nodeRef={nodeRef}</url>

The report API performs work on the data and makes XML easier to use. The formulation data, tare, cost, as well as the multi-level lists are directly usable. This API is recommended if you want to extract product data.

Please note that this API is less efficient.

This API accepts the locale parameter used to specify the language of the data, as well as the reportParams object passed in the POST content of the request.

Below is an example of reportParams, refer to the report documentation for more details on the different parameters Extractor - Part 1:

  {
   iterationKey: "bcpg:compoList",
   params: [{
     id: "param1",
     prop: "bcpg:compoListProduct|cm:name",
     // Values
     nodeRef: dataListNodeRef
     value: productName
   }],
   prefs: {
    extractInMultiLevel: "true",
    componentDatalistsToExtract: "",
    extractPriceBreaks: "true",
    mlTextFields: "cm:title",
    assocsToExtract: "bcpg:plants,bcpg:suppliers,bcpg:storageConditionsRef,bcpg:precautionOfUseRef,bcpg:nutListNut",
    assocsToExtractWithDataList: "",
    assocsToExtractWithImage : "bcpg:clients",
    multilineProperties:"bcpg:organoListValue"
   }
   nameFormat: "{entity_cm:name} - {report_cm:name} - {locale} - {param1}",
   titleFormat: "{report_cm:name} - {locale} - {param1}"

  }

Check that an entity exists

It is possible to check the existence of an entity using the following URL:

<url>/becpg/remote/check?nodeRef={nodeRef}&format={format}</url>

If the entity exists, the response will be "OK". If it does not exist, the response will be "KO".

Get or share a document

To obtain or share a document, it is necessary to use the following GET request:

<url>/becpg/remote/entity/content?nodeRef={nodeRef}&share={?true/false}</url>

If the "share" parameter is set to "true", the request will allow the document to be shared, and the share URL will be returned. If the parameter is "false" or not present, the document content will simply be returned.

Update an entity

Updating and creating an entity is done using the PUT (Create) and POST (Update) methods and the following queries:

<url>/becpg/remote/entity?nodeRef={nodeRef}</url>
<url>/becpg/remote/entity?path={path}</url>
<url>/becpg/remote/entity?query={query}</url>
<url>/becpg/remote/entity?nodeRef={nodeRef}&createVersion=true&majorVersion={majorVersion}&versionDescription={description}</url>

The content of the request must contain an XML or JSON in the default format of the remote API. It is not necessary to have all the fields. Only the present fields are created/updated.

When createVersion=true then majorVersion (true/false) and versionDescription create a new version of the entity to update. [>=2.1]

The ~ symbol can be used to indicate a relative path to the imported entity.

Example:

Example CURL request to create an entity

curl --user username:password -H "Content-Type: application/xml" -X PUT --data @sample-entity.xml http://localhost/alfresco/service/becpg/remote/entity

Sample XML to create a project sample-entity.xml

<?xml version='1.0' encoding='UTF-8'?>
<pjt:project xmlns:pjt="http://www.bcpg.fr/model/project/1.0" path="/app:company_home/st:sites/cm:simulation/cm:documentLibrary"
type="node" name="Sample project">
<pjt:projectPriority type="d:int"><![CDATA[2]]></pjt:projectPriority>
    <cm:description xmlns:cm="http://www.alfresco.org/model/content/1.0" type="d:mltext" fr="Texte - texte -texte"><![CDATA[Texte - texte -texte]]></cm:description>
<cm:name xmlns:cm="http://www.alfresco.org/model/content/1.0" type="d:text"><![CDATA[Sample project]]></cm:name>
    <cm:title xmlns:cm="http://www.alfresco.org/model/content/1.0" type="d:mltext" fr="Sample project"><![CDATA[Sample project]]></cm:title>
<pjt:projectState type="d:text"><![CDATA[Planned]]></pjt:projectState>
</pjt:project>

You can also use the JSON format which is the recommended format for creating and updating from version 3.0 of the API. This format has the advantage of allowing the updating of certain fields which was impossible before.

curl --user username:password -H "Content-Type: application/json" -X PUT --data @sample-json.json http://localhost/alfresco/service/becpg/remote/entity?format=json

For each element, the root defines the keys on which to search an element and attributes allows to specify the values to update.

Example :

{
     "entity": {
         "bcpg:erpCode": "TEST-REMOTE001",
         "cm:name":"Test remote",
         "type": "bcpg:finishedProduct",
        "params" : {
         "replaceExistingLists": true,
         "dataListsToReplace": "bcpg:allergenList,bcpg:compoList"
         },
         "attributes": {
                 "bcpg:legalName_en": "Legal Produit fini EN",
                 "bcpg:legalName": "Legal Produit fini FR",
                 "bcpg:clients": [
                         {
                             "bcpg:code": "C1"
                         },
                         {
                             "bcpg:code": "C2"
                         }
                     ],

                   "bcpg:productHierarchy2": {
"path": "/app:company_home/cm:System/cm:ProductHierarchy/bcpg:entityLists/cm:finishedProduct_Hierarchy",
"bcpg:lkvValue": "Pizza",
"type": "bcpg:linkedValue"
}
             },
         "datalists": {
           "bcpg:allergenList": [
                 {
                 "bcpg:allergenListAllergen": {
                          "bcpg:charactName": "Allergen 4"
                     },
                     "attributes": {
                         "bcpg:allergenListVoluntary": false,
                         "bcpg:allergenListInVoluntary": true
                     },
                     "type": "bcpg:allergenList"
                 }
             ],
           "bcpg:compoList": [
                 {
                  "bcpg:compoListProduct": {
                             "bcpg:code": "LSF411"
                      },
                     "attributes": {
                         "bcpg:compoListQtySubFormula": 15,
                         "bcpg:compoListUnit": "kg"
                     }
                 },
                  {
                  "bcpg:compoListProduct": {
                             "bcpg:erpCode": "TEST1"
                      },
                     "attributes": {
                         "bcpg:compoListQtySubFormula": 10,
                         "bcpg:compoListUnit": "kg"
                     }
                 }
         ]
         }
     }
}

The params attribute allows certain parameters to be passed to the API:

• replaceExistingLists (false): Allows to delete the lines in the lists not present in the JSON file [>=3.0]
• dataListsToReplace ("") : Allows to delete lines in certain lists only [>=3.0]
• failOnAssociationNotFound (true): Does not raise an error if an association is missing (unless the association is mandatory) [>=3.1]
• ignorePathOnSearch (false): If the beCPG code or the ERP code is provided then ignore the path for the search [>=3.1]

Update a multi-language property

You can import mltext type fields by specifying the value for each language:

<cm:title xmlns:cm="http://www.alfresco.org/model/content/1.0" type="d:mltext" de="Beispielprojekt" fr="Exemple de projet" en="Sample project"><![CDATA[Sample project]]></cm:title>

In json the property is followed by an underscore and the language code

"bcpg:legalName_en_US": "US value"

Update an association

An association can be identified by its nodeRef, its name, its code (beCPG or ERP) and its path

N.B: In previous versions < 2.0, you must provide a dummy nodeRef.

Example: project entity association

<pjt:projectEntity type="assoc"><bcpg:finishedProduct type="node" name="ENTITY_NAME" code="BCPG_CODE" nodeRef="FAKE_NODEREF"></bcpg:finishedProduct></pjt:projectEntity>

Delete an entity

The remote API allows entities to be deleted using the following TYPE DELETE requests:

 <url>/becpg/remote/entity?nodeRef={nodeRef}&format={format}</url>
 <url>/becpg/remote/entity?path={path}&format={format}</url>
 <url>/becpg/remote/entity?query={query}&format={format}</url>

Sample script to mass delete entities (All Materials):

#!/bin/sh
export REMOTE_SERVER=http://localhost/alfresco/service/becpg/remote/entity
export REMOTE_USER=admin
echo "Enter password"
read REMOTE_PASSWORD=

if [ $# -ne 1 ]
    then
                 #LIST
                 wget --quiet --http-user=$REMOTE_USER --http-password=$REMOTE_PASSWORD --header=Accept-Charset:iso-8859-1,utf-8 --header=Accept-Language:en-us -O list.xml $REMOTE_SERVER/list?query=%2BTYPE%3A%22bcpg %3ArawMaterial%22%20-ASPECT%3A%22sys%3Atemporary%22%20-ASPECT%3A%22bcpg%3AentityTplAspect%22
                 count=1

                 while [ -n "$nodeRef" -o $count = 1 ]
                 do
                    nodeRef=`cat list.xml | xpath -q -e //*[$count]/@nodeRef |sed s/nodeRef=//g|sed s/\"//g|sed s/\:\\\///g| xargs`

                  echo "DELETE ${nodeRef}";
                  curl --user $REMOTE_USER:$REMOTE_PASSWORD -X $REMOTE_SERVER?nodeRef=$nodeRef
                  count=$((count+1))
                 done

       exit 0
fi

Get a spec sheet

The remote API [>=2.0] also allows to download reports using the following GET methods:

 <url>/becpg/remote/report?nodeRef={nodeRef}&tplNodeRef={tplNodeRef}</url>
 <url>/becpg/remote/report?nodeRef={nodeRef}&tplNodeRef={tplNodeRef}&locale={locale}</url>
 <url>/becpg/remote/report?nodeRef={nodeRef}&tplNodeRef={tplNodeRef}&locale={locale}&format={format}</url>

• nodeRef being the system identifier of the product
• tplNodeRef being the identifier of the report model
• locale being the language code
• format being the report format (PDF, XLSX, DOCX, ODT, ZIP)

In addition, it is possible to download reports by specifying the parameters in JSON format in a POST request

Example using the CURL tool:

     #!/bin/sh

     export LOCAL_SERVER=http://localhost/alfresco/service/becpg/remote/report
     export LOCAL_USER=admin
     export LOCAL_PASSWORD=becpg

     curl --user $LOCAL_USER:$LOCAL_PASSWORD -H "Content-Type: application/json" -X POST --data @params.json "$LOCAL_SERVER?nodeRef=$1&tplNodeRef=$2" > report.pdf

The variables $1 and $2 are respectively the identifier of the product and the identifier of the report model. The params.json file contains the parameters:

     {
     iterationKey: "bcpg:plant",
     params: [{
     id: "param1",
     prop: "cm:name"
     }],
     prefs: {
     assocsToExtract: "bcpg:plants,bcpg:suppliers,bcpg:storageConditionsRef,bcpg:precautionOfUseRef,bcpg:nutListNut",
     assocsToExtractWithDataList: "bcpg:compoListProduct"
     },
     nameFormat: "{entity_cm:name}-{report_cm:name}-{locale}-{param1}",
     titleFormat: " {report_cm:name} - {locale} - {param1}"
     }

For more details on report settings see Extractor - Part 1

Create and merge a branch

The following POST requests create and merge a branch [>=V2.1] respectively:

destNodeRef is optional, by default the branch is created in the same folder as the entity.

Content of the request:

{
  "description":"Branch description"
}

Alfresco API

Alfresco also offers a REST API documented here:

https://docs.alfresco.com/5.2/pra/1/topics/pra-welcome.html

Which you can browse at this URL:

https://api-explorer.alfresco.com/api-explorer/

Appendix 1: Example queries

GET List Finished Product Sample

  curl --location --request GET 'https://$server/alfresco/service/becpg/remote/entity/list?query=+TYPE:"bcpg:finishedProduct"&format=json&fields=bcpg:legalName,bcpg:clients'

PARAMS

| query | +TYPE:"bcpg:finishedProduct" | | format | json | | fields | bcpg:legalName,bcpg:clients |

GET List of products by last modified Sample

curl --location --request GET 'https://$server/alfresco/service/becpg/remote/entity?format=json&query=(@cm\:created:[2020-02-10 TO MAX] OR @cm\ :modified:[2020-02-10 TO MAX]) AND ( TYPE:"bcpg:finishedProduct" OR TYPE:"bcpg:semiFinishedProduct")

PARAMS

| query | (@cm\:created:[2020-02-10 TO MAX] OR @cm\:modified:[2020-02-10 TO MAX]) AND ( TYPE:"bcpg:finishedProduct" OR TYPE:"bcpg:semiFinishedProduct" ) | | format | json |

Get Entity allergen list Sample

   curl --location --request GET 'https://$server/alfresco/service/becpg/remote/entity?format=json&query=+@bcpg\:erpCode:"TEST1"&lists=bcpg:allergenList&fields=bcpg:allergenListAllergen| bcpg:allergenCode,bcpg:allergenListVoluntary,bcpg:allergenListInVoluntary'

PARAMS

| query | @bcpg\:erpCode:"TEST1"| | format | json | | lists | bcpg:allergenList | | fields | bcpg:allergenListAllergen|bcpg:allergenCode,bcpg:allergenListVoluntary,bcpg:allergenListInVoluntary |

Get Compo List Sample

   curl --location --request GET 'https://$server/alfresco/service/becpg/remote/entity?format=json&query=+@bcpg\:erpCode:"TEST1"&lists=bcpg:compoList&fields=bcpg:compoListProduct, bcpg:compoListQtySubFormula,bcpg:compoListUnit'

PARAMS

| query | @bcpg\:erpCode:"TEST1"| | format | json | | lists | bcpg:compoList | | fields | bcpg:compoListProduct,bcpg:compoListQtySubFormula,bcpg:compoListUnit |

GET Get Entity

  curl --location --request GET 'https://$server/alfresco/service/becpg/remote/entity?format=json&query=+@bcpg\:erpCode:"TEST1"'

PARAMS

| query | @bcpg\:erpCode:"TEST1"| | format | json |

Appendix 2: JAVA Utility

beCPG also provides a JAVA utility library to facilitate calls to REST services. This library can be compiled from source code:

https://github.com/becpg/becpg-java-rest-api

Below is an example to retrieve an entity and its geographical origins

@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;
    }
}