Natively Pluggable Module

    @ctbto/alfresco-js-api
    TypeScript icon, indicating that this package has built-in type declarations

    4.4.0 • Public • Published

    Alfresco JavaScript API Client

    branch status
    master Build Status
    develop Build Status

    Gitter chat license

    alfresco


    Warning: This is a clone of the official @alfresco/js-api which fixes TypeScript support. Unless you are experiencing typescript errors with the official version, it's strongly recommended that you use the official version.


    This project provides a JavaScript client API into the Alfresco REST API and Activiti REST API.

    Full documentation of all the methods of each API

    Prerequisites

    The minimal supported versions are:

    Installing

    Using NPM:

    npm install @alfresco/js-api

    Using Yarn:

    yarn add @alfresco/js-api

    Authentication JS-API

    Login

    AlfrescoApi({alfrescoHost, activitiHost, contextRoot, ticket});

    Property Description default value
    hostEcm (Optional value The Ip or Name of the host where your Alfresco instance is running ) http://127.0.0.1:8080
    hostBpm (Optional value The Ip or Name of the host where your Activiti instance is running ) http://127.0.0.1:9999
    authType (Optional value can be 'BASIC' or 'OAUTH') 'BASIC'
    oauth2 (Optional configuration for SSO)
    contextRoot (Optional value that define the context Root of the Alfresco ECM API default value is alfresco ) alfresco
    contextRootBpm (Optional value that define the context Root of the Activiti API default value is activiti-app ) alfresco
    tenant (Optional value needed in case of multi tenant content service) '-default-'
    provider (Optional value default value is ECM. This parameter can accept as value ECM BPM or ALL to use the API and Login in the ECM, Activiti BPM or Both ) alfresco
    ticket (Optional only if you want login with the ticket see example below)
    disableCsrf To disable CSRF Token to be submitted. Only for Activiti call. false
    withCredentials (Optional configuration for SSO, requires CORS on ECM) false

    Login with Username and Password BPM and ECM

    Example

    const alfrescoApi = new AlfrescoApi({ provider: "ALL" });
    
    alfrescoJsApi.login("admin", "admin").then(
        (data) => {
            console.log("API called successfully Login in  BPM and ECM performed ");
        },
        (error) => {
            console.error(error);
        }
    );

    Login with Username and Password ECM

    Example

    const alfrescoJsApi = new AlfrescoApi();
    
    alfrescoJsApi.login("admin", "admin").then(
        (data) => {
            console.log("API called successfully Login ticket:" + data);
        },
        (error) => {
            console.error(error);
        }
    );
    
    // The output will be: API called successfully Login ticket: TICKET_4479f4d3bb155195879bfbb8d5206f433488a1b1

    Login with ticket

    If you already know thw ticket when you invoke the constructor you can pass it as parameter in the constructor otherwise you can call the login with ticket that will validate the ticket against the server

    Login with ticket ECM

    This authentication validate also the ticket against the server

    Example
    const ticket = "TICKET_4479f4d3bb155195879bfbb8d5206f433488a1b1";
    
    alfrescoJsApi.loginTicket(ticket).then(
        (data) => {
            console.log("valid ticket you are logged in");
        },
        (error) => {
            console.error(error);
        }
    );

    Login with ticket ECM/BPM as parameter in the constructor

    With this authentication the ticket is not validated against the server

    Example
    // Login with ECM ticket
    const alfrescoApi = new AlfrescoApi({
        ticketEcm: "TICKET_4479f4d3bb155195879bfbb8d5206f433488a1b1",
        hostEcm: "http://127.0.0.1:8080",
    });
    
    // Login with BPM ticket
    const alfrescoApi = new AlfrescoApi({
        ticketBpm: "Basic YWRtaW46YWRtaW4=",
        hostBpm: "http://127.0.0.1:9999",
    });
    
    // Login with ECM and BPM tickets
    const alfrescoApi = new AlfrescoApi({
        ticketEcm: "TICKET_4479f4d3bb155195879bfbb8d5206f433488a1b1",
        ticketBpm: "Basic YWRtaW46YWRtaW4=",
        hostEcm: "http://127.0.0.1:8080",
        hostBpm: "http://127.0.0.1:9999",
    });

    Login with Username and Password BPM

    Example

    const alfrescoApi = new AlfrescoApi({ provider: "BPM" });
    
    alfrescoJsApi.login("admin", "admin").then(
        () => {
            console.log("API called successfully Login in Activiti BPM performed ");
        },
        (error) => {
            console.error(error);
        }
    );

    Login with OAUTH2 Alfresco authorization server

    Implicit Flow

    If your want to be redirect to the authorization server and login there you can use the implicit flow to login

    oauth2 properties
    Property Description default value
    host Your oauth2 server URL null
    clientId Your clientId oauth2 null
    secret Your secret oauth2 null
    scope Your scope null
    implicitFlow true/false false
    redirectUri url to be redirect after login null
    redirectLogout url to be redirect after logout optional, if is nor present the redirectUri will be used null
    refreshTokenTimeout millisecond value, after how many millisecond you want refresh the token 30000
    redirectSilentIframeUri url to be redirect after silent refresh login /assets/silent-refresh.html
    silentLogin direct execute the implicit login without the need to call AlfrescoJsApi.implicitLogin() method false
    publicUrls list of public urls that don't need authorization. It is possible too pass absolute paths and string patterns that are valid for minimatch

    The api/js-api will automatically redirect you to the login page anf refresh the token if necessary

    Events
    Property Description default value
    implicit_redirect triggered when the user is redirect to the auth server return url parameter of the redirect
    discovery triggered when all the openId discovery url phase is terminated return an object with all the discovered url
    token_issued triggered when a new token is issued

    The api/js-api will automatically redirect you to the login page and refresh the token if necessary

    Example
    const alfrescoApi = new AlfrescoApi({
        oauth2: {
            host: "HOST_OAUTH2_SERVER",
            clientId: "YOUR_CLIENT_ID",
            secret: "SECRET",
            scope: "openid",
            implicitFlow: true,
            redirectUri: "YOUR_HOME_APP_URL",
            silentRefreshTimeout: "600000", //Optional parameter 10 minutes default value
        },
        authType: "OAUTH",
        provider: "ALL",
    });
    
    alfrescoJsApi.implicitLogin();
    Example skip login form (implicitFlow)
    const alfrescoApi = new AlfrescoApi({
        oauth2: {
            host: 'HOST_OAUTH2_SERVER',
            clientId: 'YOUR_CLIENT_ID',
            secret: 'SECRET',
            scope: 'openid',
            implicitFlow: true,
            redirectUri: 'YOUR_HOME_APP_URL',
            silentRefreshTimeout: '600000' //Optional parameter 10 minutes default value,
            silentLogin: true,
            publicUrls: ['PUBLIC_URL', 'URL_PATTERN']
        },
        authType: 'OAUTH',
        provider: 'ALL'
    });

    Password Flow

    If your auth endpoint is different from the standard one "/oauth/token" you can override it through the property authPath

    Example
    const alfrescoApi = new AlfrescoApi({
        oauth2: {
            host: "HOST_OAUTH2_SERVER",
            clientId: "YOUR_CLIENT_ID",
            secret: "SECRET",
            authPath: "my-custom-auth-endpoint/token",
        },
        authType: "OAUTH",
        provider: "ALL",
    });
    
    alfrescoJsApi.login("admin", "admin").then(
        (data) => {
            console.log(
                "API called successfully Login in with authorization server performed"
            );
        },
        (error) => {
            console.error(error);
        }
    );

    After the login if you want refresh your token you can use this call

    Example
    alfrescoJsApi.refreshToken().then(
        (data) => {
            console.log("Your token has been refreshed");
        },
        (error) => {
            console.error(error);
        }
    );

    Logout

    logout()

    Example

    alfrescoJsApi.logout().then(
        (data) => {
            console.log("Successfully Logout");
        },
        (error) => {
            console.error("Possible ticket already expired");
        }
    );

    isLoggedIn

    isLoggedIn()

    return true if you are logged in false if you are not.

    Example

    const isLoggedIn = alfrescoJsApi.isLoggedIn();
    
    if (isLoggedIn) {
        console.log("You are logged in");
    } else {
        console.log("You are not logged in");
    }

    Get tickets

    getTicketEcm()

    After the log in you can retrieve you ECM ticket

    const ecmTicket = alfrescoJsApi.getTicketEcm();
    
    console.log("This is your  ECM ticket  " + ecmTicket);

    getTicketBpm()

    After the log in you can retrieve you BPM ticket

    const bpmTicket = alfrescoJsApi.getTicketBpm();
    
    console.log("This is your BPM ticket " + bpmTicket);

    Events login/logout

    The login/logout are also an EventEmitter which you can register to listen to any of the following event types:

    • unauthorized (If this event is triggered a call to the Api was unauthorized)
    • success (If this event is triggered the login was success you can use this event > instead the login promise)
    • logout (If this event is triggered the client is successfully logout)

    Example

    alfrescoJsApi.login("admin", "admin").on("unauthorized", () => {
        console.log(
            "You are unauthorized you can use this event to redirect to login"
        );
    });
    
    alfrescoJsApi.login("admin", "admin").on("success", () => {
        console.log("Success Login");
    });
    
    alfrescoJsApi.logout().on("logout", () => {
        console.log("Successfully Logout");
    });

    Custom Endpoint

    Content service and process service has two different clients:

    • AlfrescoJsApi.ProcessClient
    • AlfrescoJsApi.ContentClient

    Both client expose a method *callApi

    callApi(
        path: string,
        httpMethod: string,
        pathParams?: any,
        queryParams?: any,
        headerParams?: any,
        formParams?: any,
        bodyParam?: any,
        contentTypes?: string[],
        accepts?: string[],
        returnType?: any,
        contextRoot?: string,
        responseType?: string
    ): Promise<any>;

    If you want call your custom rest point in one of those two service use the corresponding client.

    Example

    alfrescoJsApi.bpmClient.callApi(
        "/api/enterprise/app-version",
        "GET",
        {},
        {},
        {},
        {},
        {},
        ["application/json"],
        ["application/json"],
        { String: "String" }
    );

    Error Events

    The api/js-api has an error handler event where you can subscribe

    Example

    alfrescoJsApi.on("error", (error) => {
        console.log(error);
    });

    ECM Example

    A complete list of all the ECM methods is available here : Content API here you can find some common Example.

    BPM Example

    A complete list of all the BPM methods is available here : APS 2.X API here you can find some common Example.

    Legacy Endpoint porting (ver 2.x.x)

    Since version 3.0.0 in order to support tree shaking the JS-API has been radically redesigned.

    In order to help the porting to the new JS-APi version of the old project the previous syntax even if is deprecated is still supported in the compatibility layer.

    Note this compatibility layer could be deleted in the next major versions of the JS-API

    import { AlfrescoApiCompatibility as AlfrescoApi } from "../src/alfrescoApiCompatibility";
    
    const alfrescoJsApi = new AlfrescoApi({
        oauth2: {
            host: "HOST_OAUTH2_SERVER",
            clientId: "YOUR_CLIENT_ID",
            secret: "SECRET",
            authPath: "my-custom-auth-endpoint/token",
        },
        authType: "OAUTH",
        provider: "ALL",
    });
    
    alfrescoJsApi.login("admin", "admin").then(
        (data) => {
            console.log(
                "API called successfully Login in with authorization server performed "
            );
        },
        (error) => {
            console.error(error);
        }
    );
    
    alfrescoJsApi.nodes.getNodeInfo(fileOrFolderId).then(
        (data) => {
            console.log("This is the name" + data.name);
        },
        (error) => {
            console.log("This node does not exist");
        }
    );

    Development

    NodeJs versions newer that version 12 may have build errors.

    To run the build

    npm run build

    To run the test

    npm run test

    Keywords

    Install

    npm i @ctbto/alfresco-js-api

    DownloadsWeekly Downloads

    2

    Version

    4.4.0

    License

    Apache-2.0

    Unpacked Size

    13 MB

    Total Files

    4963

    Last publish

    Collaborators

    • garthw
    • kaindad