WEB/REST services

By default, beCPG offers an HTTP REST API service named Remote API which enables to:

• import data of an entity in xml format,
• export data of an entity in xml format according to criteria (e.g. I wish to get all validated and active products at a specific date MM/DD/YYYY).

REST service enables to create new interfaces with third party softwares such as ERP. By entity, we mean products, clients, suppliers, projects... with all their information and, these, dynamically and without development.

The exchange interface can be realized by a third party tool to:

• manage exchanges,
• manage flows (for example, with transformation rules on list of values),
• handle errors.

That third party tool uses the Remote API to import and export data in beCPG. 2 ways of approach are possible:

• the client has a third party tool capable of creating the interface,
• the client wishes that beCPG puts in place a third patty tool to create the interface

In addition to that, most APIs are accessible by REST services:

• CRUD operations, Create/Read/Update/Delete
• formulation
• document generation
• versions and reports recovery
• etc...

Versions

Different API versions exist depending on your version of beCPG. Descending compatibility is maintained. For example, XML format is identical between version 1 and 3.1.

See below for the different API versions with the list of major changes between versions.

Below the associated beCPG versions.

Specific options to each API version [>= 3.1] are indicated in the documentation.

API beCPG

beCPG's remote API gives the following URL REST:

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/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>

POST/GET/PUT/DELETE methods allow respectively to add, find, update and delete entities in PLM (products, clients, suppliers etc)

Listing entities

The list of entities is obtained with LIST requests and can be filtered with advanced research criteria (last modified product since "specific date").

<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>

Search syntax is Lucene FTS Alfresco ¹ and is available here: http://docs.alfresco.com/5.0/concepts/rm-searchsyntax-intro.html

¹. For more information, please read the part on the creation of Lucene requests which is available here documentation ↩

Warning depending on the syntax used, the search may have a lag of a few minutes with the modifications made to the system. This time is related to indexing. To avoid this, it is recommended that you only use searches using the db-afts syntax. If this is not the case, the search criteria must be shifted by 10 min. To test that your query is db-afts compatible, use the node browser in run db-afts, your search should return results.

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

• RELATIVE
• TYPE
• ASPECT
• EXACT TYPE
• ACCURATE APPEARANCE -= (Equal Ownership)
• Date range
• AND NOT OR

More information on transactional searches:

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

Example of request to find a finished product with its ERP code:

+TYPE:"bcpg:finishedProduct" AND +@bcpg\\:erpCode:"codeErp" AND -ASPECT:"bcpg:compositeVersion"
(-ASPECT:"bcpg:compositeVersion" allows to ignore old versions)

Linked 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 encrypted URL (in the firefox console):

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

The maxResults parameter enables to specify a number of results (-1 to get all results)
The fields parameter enables to specify fields or associations which need to be extracted in the results. The format paramater enables to specify the output format

• format=xml (by default)
• format=json (json format)

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

Examples:

Example of a script script bash allowing to directly recover a list of entities in xml format:

#!/bin/sh

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

# Recovering 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 "\Obtention du noeud $nodeRef"; 
      #Each node is saved
      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

Getting an entity

To get entities, two REST services are available:

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>

Format enables to modify the XML format of the response:

• format=xml (by default)
• format=json (json format) [>= 3.0]
• format=json_schema (JSON Validation Schema) [>= 4.2.1]
• format=xml_all (contains details of all associations)
• format=xml_excel (adapted format for use as datasource in excel)
• format=xml_light (that format does not contain child associations)
• format=xsd (that format enables XSD extraction)
• format=xsd_excel (that format allows XSD extraction for excel)

You can also get additional filter parameters. There are 3 types of filter [>=2.0]:

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

Also, you can extract the properties of an association by putting in the fields parameter, the association's names and their properties, by respecting the following format : ASSOC_Name1|PROP_Name1,ASSOC_Name1|PROP_Name2. 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 JSON format, the parameter params enables to pass certain API parameters [>=3.1]:

• appendCode (true) : Disable the addition of beCPG code
• appendErpCode (true) : Disable the addition of ERP code
• appendMlTextConstraint (true) : Disable the addition of multilingual constraints
• appendNodeRef (true) : Disable the addition of the ID
• appendDataListNodeRef (true) : Disable the addition of the datalist nodes ID
• appendContent (false) : Enables to add JSON file content

That parameter is for the JSON format

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

Et doit être encodé dans la requête

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

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

Getting information through API report

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

The API report works data and enables to get an easier to use XML. Formulation data, tare, cost, and multilevel lists are directly usable. That API is advised for use if you want to extract product data.

Warning, that API is less efficient.

That API accepts local parameter enabling to specify language data, as the object reportParams which went in the post content of the request.

Below is an example for reportParams. For more information, please read our documentation on report parameters in the chapter reports Extracteur - Partie 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}"

 }

Share a document

To share a document, use the following GET request :

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

The parameter share=true enables to share the document and returns the document share.

Updating an entity

The update and creation of an entity is done by using PUT (creation) and POST (update) methods with the following requests:

<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 a request must contain an XML in the by default format of the remote API. It is not necessary to have all fields. Only present fields are created/updated. When createVersion=true then majorVersion (true/false) and versionDescription enable to create a new version of the entity which must be updated. [>=2.1]

Example:

Example of a CURL request used 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

Example of XML enabling 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.2. This format has the advantage of allowing certain fields to be updated beforehand.

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 for an element and attributes makes it possible 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 you to pass certain parameters to the API:

• replaceExistingLists (false) : Enable to delete lines in lists which are not present in the JSON file [>=3.0]
• dataListsToReplace ("") : Enable to delete lines in specific lists [>=3.0]
• failOnAssociationNotFound (true) : Only raise an error if an association is missing (except if the association is mandatory) [>=3.1]
• ignorePathOnSearch (false) : If the beCPG code or the ERP code is provided then the path is ignored for the search [>=3.1]

Update of a multi-language property

Since 2.2.X PLM version, you can import mltext fields in multi-languages, for example import the title property:

<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": "Valeur US"

Update Associations

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

N.B: Before 2.2.X PLM version, you are supposed to provide a fake nodeRef.

Example :

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

Deleting an entity

the remote API enables to delete entities 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>

Example of a script enabling to delete multiple 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

Download reports

The Remote API [>=2.0] makes it easier to download reports files 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>

Where:

• nodeRef being the product nodeRef
• tplNodeRef being the report template nodeRef
• locale being the language code
• format being the report format which can be (PDF, XLSX, DOCX, ODT, ZIP)

Also, you can download customizable reports using POST method and pass in the body parameters as a JSON object

Example: Download custom report using CURL

#!/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

Where $1 represents the product id and $2 represents the report template id.

    {
    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 customization using report parameters, please read 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"
}

API Alfresco

Alfresco also provides API REST. For more information on that please use the following link:

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

and

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

Annex: Request examples

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 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 |

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