Alfresco met à disposition une API sous la forme de services web HTTP. Ceci permet d’interconnecter des entrepôts de documents avec d’autres applications.

Cet article présente rapidement comment les utiliser avec des exemples en java puis comment les étendre avec un exemple de web script Alfresco, de manière à ajouter de nouvelles fonctionnalités.

Utilisation des services web Alfresco

Authentification

Pour utiliser les différents services web Alfresco, il est nécessaire dans un premier temps de s’authentifier. L’authentification permet de récupérer un “ticket d’authentification” qui sera nécessaire pour effectuer les appels aux services web Alfresco.

Note : Un ticket d’authentification a une durée de vie limitée dans le temps. Lorsqu’il expire, il faudra procéder à une reconnexion. Un nouveau ticket sera alors généré.

Description du service web :

Exemple :

L’exemple ci-dessous illustre comment récupérer le ticket d’authentification depuis une application java.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
...
HttpClient httpClient = getHttpClient();
HttpPost postRequest = new HttpPost();
URIBuilder builder = new URIBuilder();
builder.setScheme("https");
builder.setHost("mon-server-alfresco.atolcd.com");
builder.setPath("/alfresco/service/api/login");
StringEntity entity;
try {
    URI uri = builder.build();
    postRequest.setURI(uri);
    postRequest.addHeader("Accept", "application/json");
    entity = new StringEntity("{\"username\":\"mon_login\",\"password\":\"mon_mot_de_passe\"}");
    postRequest.setEntity(entity);
    HttpResponse response = httpClient.execute(postRequest);
 
    if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
        if (response.getStatusLine().getStatusCode() == HttpStatus.SC_FORBIDDEN) {
            // 403 dans notre cas mauvais login et/ou mot de passe
            throw new GedAuthenticateException("Login et/ou mot de passe incorrects");
        } else {
            throw new GedException("Erreur HTTP code : " + response.getStatusLine().getStatusCode());
        }
    }
    // Lecture de la réponse
    BufferedReader br = new BufferedReader(new inputStreamReader((response.getEntity().getContent())));
    String output;
    StringBuffer jsonResponse = new StringBuffer();
    while ((output = br.readLine()) != null) {
        jsonResponse.append(output);
    }
 
    try {
       JSONObject json = new JSONObject(jsonResponse.toString());
        // On récupère la valeur du ticket retournée qu’on utilisera pour les appels aux autres web services
        String mon_ticket_pour_alfresco = json.getJSONObject("data").getString("ticket");
    } catch (JSONException e) {
       ....
     }
} catch (Exception e) {
   ….
}
 

# Téléversement de document

Par défaut, Alfresco met à disposition une API de téléversement de document.

Description du service web :

Exemple :

L’exemple ci-dessous illustre l’utilisation d’un web script de téléversement de document personnalisé lié à un contexte métier qui nécessite la saisie de métadonnées supplémentaires depuis une application java. Le web script est fourni un peu plus loin dans cet article.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
…
String filename = "/var/tmp/dossier_NUM0098.pdf";
File initialFile = new File(filename);
InputStream inputStream = new FileInputStream(initialFile);
 
URIBuilder builder = new URIBuilder();
builder.setScheme("https");
builder.setHost("mon-server-alfresco.atolcd.com");
builder.setPath("/alfresco/service/mon_application_metier/ajouter_un_document");
builder.setParameter("alf_ticket", mon_ticket_pour_alfresco);
 
URI uri = builder.build();
HttpPost postRequest = new HttpPost(uri);
 
// Préparation des données à transmettre
MultipartEntityBuilder builderME = MultipartEntityBuilder.create().setStrictMode();
builderME.setCharset(Charset.forName("UTF-8"));
builderME.addPart("filesToUp", new InputStreamBody(inputStream, filename));
builderME.addTextBody("numero_dossier", "NUM0098", MULTIPART_FORM_DATA);
builderME.addTextBody("nom_document", "dossier_NUM0098.pdf", MULTIPART_FORM_DATA);
builderME.addTextBody("marque", "APPLE", MULTIPART_FORM_DATA);
builderME.addTextBody("modele", "IPHONE X", MULTIPART_FORM_DATA);
 
// Transmission des données au web scripts
HttpEntity entity = builderME.build();
postRequest.setEntity(entity);
HttpResponse response = httpClient.execute(postRequest);
 
if (response.getStatusLine().getStatusCode() == HttpStatus.SC_UNAUTHORIZED) {
    // Le ticket plus valide, il faut faire une nouvelle authentification pour récupérer un ticket valide
   …
} else if (response.getStatusLine().getStatusCode() == HttpStatus.SC_OK) {
    // Le document a été inséré avec succès dans alfresco
    …
} else {
   // Autres erreurs
    …
}
 

Téléchargement

Un web service Alfresco permet de télécharger un document à partir du nodeRef du document (identifiant du document dans Alfresco).

Le nodeRef doit être connu par l’application consommatrice. Il peut être récupéré lors d’une synchronisation ou à la volée via une recherche (appel à un web service proposé en standard ou métier).

Description du service web :

  • URL : {url_alfresco}/alfresco/d/a/workspace/SpacesStore/{nodeId}/{filename}?ticket={ticket}
  • Méthode : GET
  • Paramètres :
    • nodeId : Identifiant interne alfresco du document
    • filename : Nom du document
    • ticket : Numéro du ticket récupéré à l’authentification

Exemple :

L’exemple ci-dessous illustre l’utilisation d’un web script de téléchargement d’un document depuis une application java.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
…
 
String nodeRef = "ae5177a0-50a4-4755-a1e9-f17a449129b67";
String filename = "dossier_NUM0098.pdf";
URIBuilder builder = new URIBuilder();
builder.setScheme("https");
builder.setHost("mon-server-alfresco.atolcd.com");
builder.setPath( "/alfresco/d/a/workspace/SpacesStore".concat(nodeRef).concat("/").concat(nomFichier));
builder.setParameter("ticket", mon_ticket_pour_alfresco);
 
URI uri = builder.build();
HttpGet getRequest = new HttpGet(uri);
HttpResponse response = httpClient.execute(getRequest);
 
if (response.getStatusLine().getStatusCode() == HttpStatus.SC_UNAUTHORIZED) {
    // Le ticket n’est plus valide, il faut faire une nouvelle authentification pour récupérer un ticket valide
    ...
} else if (response.getStatusLine().getStatusCode() == HttpStatus.SC_OK) {
     // Téléchargement du fichier (Transformation du InputStream en fichier)
    InputStream is = response.getEntity().getContent();
    File targetFile = new File("/var/tmp/".concat(nomFichier));
    OutputStream outStream = new FileOutputStream(targetFile);
    byte[] buffer = new byte[8 * 1024];
    int bytesRead;
    while ((bytesRead = is.read(buffer)) != -1) {
        outStream.write(buffer, 0, bytesRead);
    }
    IOUtils.closeQuietly(outStream);
 
} else {
    // Autres erreurs
    ...
}
 

Déconnexion

Un service web Alfresco permet d’invalider un ticket d’authentification.

Description du service web :

  • URL : {url_alfresco}/alfresco/service/api/login/ticket/{ticket}
  • Méthode : GET
  • Paramètre :
    • ticket : Numéro du ticket récupéré à l’authentification
  • Lien vers la documentation officielle

Exemple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
…
 
HttpClient httpClient = getHttpClient();
HttpDelete deleteRequest = new HttpDelete();
try {
    URIBuilder builder = new URIBuilder();
    builder.setScheme("https");
    builder.setHost("mon-server-alfresco.atolcd.com");
    builder.setPath("/alfresco/service/api/login/ticket/".concat(mon_ticket_pour_alfresco));
    builder.setParameter("alf_ticket", mon_ticket_pour_alfresco);
    URI uri = builder.build();
    deleteRequest.setURI(uri);
 
    HttpResponse response = httpClient.execute(deleteRequest);
    …
 
}
...
 

Créer un web script lié à un contexte spécifique

Alfresco offre également la possibilité de créer ses propres web services via la mise en place de web scripts Alfresco. Par exemple, il est possible de créer sa propre méthode d’upload avec métadonnées métiers via des web scripts Alfresco.

L’intérêt d’utiliser sa propre méthode est multiple :

  • Effectuer plusieurs contrôles de validation (Exemple : type de fichier, taille max)
  • Placer le fichier dans une arborescence définie à l’avance selon des règles bien spécifiques
  • Enrichir la description du document via des métadonnées propres à une contexte métier (Exemple : Nature du document, longitude, latitude, etc …)

Extrait du code source du web script mis en place coté Alfresco (document.post.js) :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
function main() {
var DOSSIERS_PATH = "/Applications/MON_APPLICATION/Dossiers";
 
if (!formdata.hasField("numero_dossier")) {
         mandatoryField("numero_dossier");
          return;
}
 
if (!formdata.hasField("nom_document")) {
         mandatoryField("nom_document");
         return;
}
 
if (!formdata.hasField("marque")) {
         mandatoryField("marque");
         return;
}
 
if (!formdata.hasField("modele")) {
         mandatoryField("modele");
         return;
}
 
var file = null;
for each (field in formdata.fields) {
         if (field.isFile) {
                 file = field;
         }
}
if(file === null) {
         mandatoryField("fileToUp");
         return;
}
 
if(file.content.getContent().length() <= 1) {
       status.code = 400;
       status.message = "Le fichier est vide : 0 octet";
       return;
}
 
// Vérification si répertoire MON_APPLICATION existe
var folderMyApp = companyhome.childByNamePath("/Applications/MON_APPLICATION");
if(folderMyApp === null) {
       var parentFolder = companyhome.childByNamePath("/Applications");
       folderMyApp = parentFolder.createFolder("MON_APPLICATION");
}
 
// Vérifcation si répertoire Dossiers existe
var folderDossiers = companyhome.childByNamePath("/Applications/MON_APPLICATION/Dossiers");
if(folderDossiers === null) {
       folderDossiers = folderMyApp.createFolder("Dossiers");
}
 
// Vérification existence du numero_dossier (dossier cible)
var folderDest = folderDossiers.childByNamePath(args.numero_dossier);
if(folderDest === null) {
         folderDest = folderDossiers.createFolder(args.numero_dossier);
}
 
var fileExist = folderDest.childByNamePath(args.nom_document);
if(fileExist === null) {
         var newFile = folderDest.createFile(args.nom_document, "su:mon_type_de_doc_personnalise");
         newFile.properties.content.write(file.content, false, true);
         newFile.properties["su:numerodossier"] = args.numero_dossier;
         newFile.properties["su:marque"] = args.marque;
         newFile.properties["su:modele"] = args.modele;
                 ...
         newFile.save();
         newFile.move(folderDest);
 
         status.code = 200;
         status.message = "Document ajouté avec succès";
         return;
}else {
         status.code = 409;
         status.message = "Fichier déjà existant";
         return;
}
}
 
function mandatoryField(field) {
    status.code = 400;
    status.message = "Paramètre '" + field + "' manquant";
}
 
main();
 



Note :  Les exemples de cet article s’appuient sur des extraits de code d’une application java communicant avec une version 4.x d’Alfresco. D’une version à l’autre, les paramètres et noms des web services sont susceptibles d’évoluer.

Tweetez
Partagez
Partagez
0 Partages