Alfresco JavaScript API Client
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
- Node
- Api Modules complete methods list
- Install
- Use
- Authentication JS-API
- Custom Endpoint
- ECM
- BPM
- Error Events
- Development
- Release History
Full documentation of all the methods of each API
Prerequisites
To correctly use the alfresco js api the minimal supported version are:
- 5.2.a-EA Alfresco Platform Repository (version 5.2.a-EA or newer)
- 1.5 Activiti
Node
To correctly use the alfresco-js-api in node check that on your machine is running Node version 5.0.0 or higher.
Api Modules complete methods list
- Authentication API
- Core API
- Governance core API
- Governance classification API
- Discovery API
- Search API
- Activiti API
- Mock API
Install
Installer for browser versions:
npm install --save alfresco-js-api
Installer for node versions:
npm install --save alfresco-js-api-node
Use
Import library for node projects
var AlfrescoApi = ;
Import library for browser projects
or for not minify version
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 |
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 |
Login with Username and Password BPM and ECM
Example
thisalfrescoJsApi = provider:'ALL' ; thisalfrescoJsApi;
Login with Username and Password ECM
Example
thisalfrescoJsApi = ; thisalfrescoJsApi; //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
var ticket = 'TICKET_4479f4d3bb155195879bfbb8d5206f433488a1b1'; thisalfrescoJsApi;
Login with ticket ECM/BPM as parameter in the constructor
With this authentication the ticket is not validated against the server
Example
//Login ticket ECMthisalfrescoJsApi = ticketEcm:'TICKET_4479f4d3bb155195879bfbb8d5206f433488a1b1' hostEcm:'http://127.0.0.1:8080'; //Login ticket BPMthisalfrescoJsApi = ticketBpm: 'Basic YWRtaW46YWRtaW4=' hostBpm:'http://127.0.0.1:9999'; //Login ticket ECM and BPMthisalfrescoJsApi = 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
thisalfrescoJsApi = provider:'BPM' ; thisalfrescoJsApi;
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 youw ant refresh the token | 40000 |
silentLogin | direct execute the implicit login without the need od call this.alfrescoJsApi.implicitLogin() method | false |
The alfresco-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 returnl an object with all the discovered url | |
token_issued | triggered when a new token is issued |
The alfresco-js-api will automatically redirect you to the login page anf refresh the token if necessary
Example
thisalfrescoJsApi = 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'; thisalfrescoJsApi;
Example skip login form
thisalfrescoJsApi = 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 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
thisalfrescoJsApi = oauth2: host: 'HOST_OAUTH2_SERVER' clientId: 'YOUR_CLIENT_ID' secret: 'SECRET' authPath:'my-custom-auth-endpoint/token' authType: 'OAUTH' provider: 'ALL' ; thisalfrescoJsApi;
After the login if you want refresh your token you can use this call
Example
thisalfrescoJsApi;
Logout
logout()
Example
thisalfrescoJsApi;
isLoggedIn
isLoggedIn()
return true if you are logged in false if you are not.
Example
var isLoggedIn = thisalfrescoJsApi; if isLoggedIn console; else console;
Get tickets
getTicketEcm()
After the log in you can retrieve you ECM ticket
var ecmTicket = thisalfrescoJsApi ; console;
getTicketBpm()
After the log in you can retrieve you BPM ticket
var bpmTicket = thisalfrescoJsApi; console;
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
thisalfrescoJsApi; thisalfrescoJsApi; thisalfrescoJsApi;
Custom Endpoint
Content service and process service has two different clients:
- this.alfrescoJsApi.bpmClient
- this.alfrescoJsApi.ecmClient
Both client expose a method *callApi
: Promise<any>;
If you want call your custom rest point in one of those two service use the corrispondin client.
Example
thisalfrescoJsApibpmClient
ECM
A complete list of all the ECM methods is available here : Core API. Below you can find some common examples.
Get Node content
getFileContent(nodeId, opts)
Returns the file content of the node with identifier nodeId.
### Example
var nodeId = '80a94ac8-3ece-47ad-864e-5d939424c47c'; thisalfrescoJsApicorenodesApi;
Get File or Folder Info
getNodeInfo(fileOrFolderId, opts)
Get information for the File/Folder with the identifier nodeId. The identifier of a node. You can also use one of these well-known aliases: -my- , -shared- or -root- as NodeId
Example
var fileOrFolderId = '80a94ac8-3ece-47ad-864e-5d939424c47c'; thisalfrescoJsApinodes;
Get Folder Children Info
getNodeChildren(fileOrFolderId, opts)
Minimal information for each child is returned by default. You can use the include parameter to return additional information. returns a promise with the Info about the children of the node if resolved and {error} if rejected. You can also use one of these well-known aliases: -my- , -shared- or -root- as NodeId
Example
var folderNodeId = '80a94ac8-3ece-47ad-864e-5d939424c47c'; thisalfrescoJsApinodes;
Create Folder
createFolder(name, relativePath, nodeIdParentFolder, opts)
createFolder return a promise that is resolved if the folder is created and {error} if rejected. You can also use one of these well-known aliases: -my- , -shared- or -root- as nodeIdParentFolder
Example
thisalfrescoJsApinodes; thisalfrescoJsApinodes; var parentFolder = '80a94ac8-3ece-47ad-864e-5d939424c47c' thisalfrescoJsApinodes;
CreateFolder With Auto Rename
createFolderAutoRename(name, relativePath, nodeIdParentFolder, opts)
is the same of createFolder(name, relativePath, nodeId, {autoRename: true}) is just syntactic sugar You can also use one of these well-known aliases: -my- , -shared- or -root- as nodeIdParentFolder
Example
thisalfrescoJsApinodes;
Upload File
uploadFile(fileDefinition, relativePath, nodeId, nodeBody, opts)
uploadFile return a promise that is resolved if the file is successful uploaded and {error} if rejected.
The fileDefinition provides information about files and allows JavaScript to access their content.
*Web File Definition File Definition are generally retrieved from a FileList object returned as a result of a user selecting files using the element
*Node File Definition File Definition are generally retrieved from a read Stram
Example
var fs = ; var fileToUpload = fs; thisalfrescoJsApiupload ; thisalfrescoJsApiupload ; thisalfrescoJsApiupload ; var parentFolder = '80a94ac8-3ece-47ad-864e-5d939424c47c'; thisalfrescoJsApiupload ;
The default behaviour of the Upload API will not create any thumbnail.
In order to create a thumbnail you have to perform to pass the parameter javascript{renditions: 'doclib'}
as in the example below.
This parameter will basically perform also a call to the Rendition API.
For more information about the Rendition API :
var fs = ; var fileToUpload = fs; thisalfrescoJsApiupload ;
- To abort a file uploading
var fs = ; var fileToUpload = fs; var promiseUpload = thisalfrescoJsApiupload ; promiseUpload;
Events Upload File
The uploadFile is also an EventEmitter which you can register to listen to any of the following event types:
- progress
- success
- abort
- error
- unauthorized
Example
var fs = ; var fileToUpload = fs; thisalfrescoJsApiupload ;
Delete File or Folder
deleteNode(fileOrFolderId)
Delete File/Folder with the identifier nodeId, if the nodeId is a folder, then its children are also deleted Deleted nodes move to the trash bin is still possible to recover it
Example
var fileOrFolderId = '80a94ac8-3ece-47ad-864e-5d939424c47c'; thisalfrescoJsApinodes;
Delete File or Folder Permanent
deleteNodePermanent(fileOrFolderId)
Delete File/Folder with the identifier nodeId, if the nodeId is a folder, then its children are also deleted If Deleted Permanent is used will not be possible recover the files
Example
var fileOrFolderId = '80a94ac8-3ece-47ad-864e-5d939424c47c'; thisalfrescoJsApinodes;
Get thumbnail Url
getDocumentThumbnailUrl(documentId)
Example
var thumbnailUrl = thisalfrescoJsApicontent;
Get preview Url
getDocumentPreviewUrl(documentId)
Example
var previewUrl = thisalfrescoJsApicontent;
Get content Url
getContentUrl(documentId)
Example
var contentUrl = thisalfrescoJsApicontent;
Custom web scripts call
For mor information about web scripts read the Wiki and the Wiki with Web ScriptsExamples
executeWebScript(httpMethod, scriptPath, scriptArgs, contextRoot, servicePath)
Anatomy of a Web Script URI http(s)://(host):(port)/(contextPath)/(servicePath)/(scriptPath)?(scriptArgs) A Web Script is simply a service bound to a URI which responds to HTTP methods such as GET, POST, PUT and DELETE. While using the same underlying code, there are broadly two kinds of Web Scripts.
Parameters
Name | Description |
---|---|
httpMethod | possible value GET, POST, PUT and DELETE |
scriptPath | path to Web Script (as defined by Web Script) |
scriptArgs | arguments to pass to Web Script |
contextRoot | path where application is deployed default value 'alfresco' |
servicePath | path where Web Script service is mapped default value 'service' |
postBody | post body |
//Call a GET on a Web Scripts available at the following URIs: http://127.0.01:8080/alfresco/service/mytasks thisalfrescoJsApicorewebscriptApi; //Call a GET on a Web Scripts available at the following URIs: http://127.0.01:8080/share/service/mytasks thisalfrescoJsApicorewebscriptApi; //Call a GET on a Web Scripts available at the following URIs: http://127.0.01:8080/share/differentServiceSlug/mytasks thisalfrescoJsApicorewebscriptApi;
BPM
A complete list of all the BPM methods is available herActiviti API. Below you can find some common examples.
Task Api
Below you can find some example relative to the Activiti process api for all the possible method go to Task Api documentation
List Task
listTasks(requestNode)
return a list of task based on the requestNode query
Parameters
Name | Type | Description |
---|---|---|
requestNode | Representation | requestNode |
Example
var requestTasks = ; thisalfrescoJsApiactivititaskApi;
Get Task
getTask(taskId)
return the TaskRepresentation of single task by id
Parameters
Name | Type | Description |
---|---|---|
taskId | String | taskId |
Example
var taskId = '10'; // String | taskId thisalfrescoJsApiactivititaskApi;
Filter Task
filterTasks(requestTasks)
return the ResultListDataRepresentation that is a list of all the task filered
Parameters
Name | Type | Description |
---|---|---|
requestTasks | TaskFilterRequestRepresentation | requestTasks |
Example
var requestTasks = ;requestTasksappDefinitionId = 1; thisalfrescoJsApiactivititaskApi;
Complete Task
completeTask(taskId)
To complete a task (standalone or without a task form) :
Parameters
Name | Type | Description |
---|---|---|
taskId | String | taskId |
Example
var taskId = '10'; // String | taskId thisalfrescoJsApiactivititaskApi;
Get Task Form
getTaskForm(taskId)
Retrieve the Task Form representation. FormDefinitionRepresentation
Parameters
Name | Type | Description |
---|---|---|
taskId | String | taskId |
Example
var taskId = '10'; // String | taskId thisalfrescoJsApiactivititaskApi;
Complete Task Form
completeTaskForm(taskId, completeTaskFormRepresentation)
Complete a Task Form
Parameters
Name | Type | Description |
---|---|---|
taskId | String | taskId |
completeTaskFormRepresentation | CompleteFormRepresentation | completeTaskFormRepresentation |
Example
var taskId = '10'; // String | taskId thisalfrescoJsApiactivititaskApi;
Process Api
Below you can find some example relative to the Activiti process api for all the possible method go to Process Api documentation
Get Process Instances
getProcessInstances(requestNode)
Retrieve a list of process instances ResultListDataRepresentation
Parameters
Name | Type | Description |
---|---|---|
requestNode | ProcessFilterRequestRepresentation | requestNode |
Example
var requestNode = ; thisalfrescoJsApiactivitiprocessApi;
Filtered process:
var requestNode = ; requestNodepage = 0;requestNodesort = 'created-desc';requestNodestate = 'completed'; thisalfrescoJsApiactivitiprocessApi;
Models Api
Below you can find some example relative to the Activiti process api for all the possible method go to Task Api documentation
Get Model
getModel(modelId, opts)
To retrieve details about a particular model (process, form, decision rule or app) return a ModelRepresentation
Parameters
Name | Type | Description | Notes |
---|---|---|---|
modelId | Integer | modelId | |
includePermissions | Boolean | includePermissions | [optional] |
Example
var opts = 'filter': 'myReusableForms' 'modelType': 2; thisalfrescoJsApiactivitimodelsApi;
Report Api
Below you can find some example relative to the Activiti report api for all the possible method go to Report Api documentation
Create default Reports
createDefaultReports()
Create the default reports
Parameters
No parameters required.
Example
thisalfrescoJsApiactivitireportApi;
Get Reports
getReportList()
Retrieve the available report list
Parameters
No parameters required.
Example
thisalfrescoJsApiactivitireportApi;
Report Params
getReportParams(reportId)
Retrieve the parameters referring to the reportId.
Parameters
Name | Type | Description | Notes |
---|---|---|---|
reportId | String | reportId |
Example
var reportId = "1"; // String | reportId thisalfrescoJsApiactivitireportApi;
Report Process Definitions
getProcessDefinitions()
Retrieve the process definition list for all the apps.
Parameters
No parameters required.
Example
thisalfrescoJsApiactivitireportApi;
Tasks of process definition
getTasksByProcessDefinitionId(reportId, processDefinitionId)
Retrieves all tasks that refer to the processDefinitionId
Parameters
Name | Type | Description | Notes |
---|---|---|---|
reportId | String | reportId | |
processDefinitionId | String | process definition id |
Example
var reportId = "1"; // String | reportIdvar processDefinitionId = "1"; // String | processDefinitionId thisalfrescoJsApiactivitireportApi;
Generate reports
getReportsByParams(reportId, paramsQuery)
Generate the reports based on the input parameters
Parameters
Name | Type | Description | Notes |
---|---|---|---|
reportId | String | reportId | |
paramsQuery | Object | Query parameters |
Example
var reportId = "1"; // String | reportIdvar paramsQuery = status: 'ALL'; // Object | paramsQuery thisalfrescoJsApiactivitireportApi;
Update report details
updateReport(reportId, name)
Update the report details
Parameters
Name | Type | Description | Notes |
---|---|---|---|
reportId | String | reportId | |
name | String | The report name |
Example
var reportId = "1"; // String | reportIdvar name = "new Fake name"; // String | reportId thisalfrescoJsApiactivitireportApi;
Export to csv
exportToCsv(reportId, queryParms)
Export a report as csv
Parameters
Name | Type | Description | Notes |
---|---|---|---|
reportId | String | reportId | |
queryParms | Object | Query parameters |
Example
var reportId = "1"; // String | reportIdvar queryParms = 'processDefinitionId': 'TEST:99:999' 'dateRange': 'startDate': '2017-01-01T00:00:00.000Z' 'endDate': '2017-01-24T23:59:59.999Z' 'rangeId': 'currentYear' 'slowProcessInstanceInteger': 10 'status': 'All' '__reportName': 'FAKE_REPORT_NAME' ; thisalfrescoJsApiactivitireportApi;
Save Report
saveReport(reportId, queryParams)
Save a report
Parameters
Name | Type | Description | Notes |
---|---|---|---|
reportId | String | reportId | |
queryParms | Object | Query parameters |
Example
var reportId = "1"; // String | reportIdvar queryParms = 'processDefinitionId': 'TEST:99:999' 'dateRange': 'startDate': '2017-01-01T00:00:00.000Z' 'endDate': '2017-01-24T23:59:59.999Z' 'rangeId': 'currentYear' 'slowProcessInstanceInteger': 10 'status': 'All' '__reportName': 'FAKE_REPORT_NAME' ; thisalfrescoJsApiactivitireportApi;
Delete report
deleteReport(reportId)
Delete a report
Parameters
Name | Type | Description | Notes |
---|---|---|---|
reportId | String | reportId |
Example
var reportId = "1"; // String | reportId thisalfrescoJsApiactivitireportApi;
Error Events
The alfresco-js-api has an error handler event where you can subscribe
Example
thisalfrescoJsApi
Development
-
To run the build
$ npm run build
-
To run the build in watch mode
$ npm run watchify
-
To run the test
$ npm run test
-
To run the test coverage
$ npm run coverage
Release History
Read the Changelog