alfresco-ng2-components/docs/process.service.md

Process Service

Manage Process Instances, Process Variables, and Process Audit Log.

Importing

import { ProcessService, ProcessInstance, ProcessInstanceVariable, 
         ProcessDefinitionRepresentation, ProcessFilterParamRepresentationModel, TaskDetailsModel } from '@alfresco/adf-process-services';

export class SomePageComponent implements OnInit {

  constructor(private processService: ProcessService) {
  }

Methods

getProcess(processInstanceId: string): Observable<ProcessInstance>

Get Process Instance metadata for passed in Process Instance ID:

const processInstanceId = '11337';
this.processService.getProcess(processInstanceId).subscribe( (processInstance: ProcessInstance) => {
  console.log('ProcessInstance: ', processInstance);
  }, error => {
    console.log('Error: ', error);
  });

The processInstanceId refers to a process instance ID for a running process in APS.
The returned processInstance object is of type ProcessInstance and looks like in this sample:

   businessKey: null
   ended: null
   graphicalNotationDefined: true
   id: "11337"
   name: "Invoice Approval 2 started from ADF client"
   processDefinitionCategory: "http://www.activiti.org/processdef"
   processDefinitionDeploymentId: "18"
   processDefinitionDescription: "This is a simple invoice approval process that allows a person to assign a dedicated approver for the the invoice. It will then be routed to the Accounting department for payment preparation. Once payment is prepared the invoice will be stored in a specific folder and an email notification will be sent."
   processDefinitionId: "InvoiceApprovalProcess:2:21"
   processDefinitionKey: "InvoiceApprovalProcess"
   processDefinitionName: "Invoice Approval Process"
   processDefinitionVersion: 2
   startFormDefined: true
   started: Tue Oct 10 2017 10:35:42 GMT+0100 (BST) {}
   startedBy: {id: 1, firstName: null, lastName: "Administrator", email: "admin@app.activiti.com"}
   suspended: false
   tenantId: "tenant_1"
   variables:  
        0: {name: "initiator", type: "string", value: "1"}
        1: {name: "approver", type: "long", value: 2002}
        2: {name: "companyemail", type: "string", value: "martin.bergljung@xxxxx.com"}
        3: {name: "invoicetobeapproved", value: null}
        4: {name: "invoiceFileName", type: "string", value: " - [Alfresco_Enterprise_Edition_3_3_Windows_Simple_Install.pdf]"}
        5: {name: "comments", value: null}
        6: {name: "form8outcome", type: "string", value: "Reject"}

startProcess(processDefinitionId: string, name: string, outcome?: string, startFormValues?: any, variables?: ProcessInstanceVariable[]): Observable<ProcessInstance>

Start a process based on passed in Process Definition, name, form values or variables.

When starting you can choose to pass in form field values or process variables (you cannot pass in both). Here is an example of how to pass in form field values, these correspond to the start form that has been defined for the process:

const processDefinitionId = 'InvoiceApprovalProcess:2:21';
const name = 'Sample Invoice Process';
const outcome = null;
const startFormValues = {
  approver: 'admin@app.activiti.com',
  companyemail: 'someone@acme.com',
  invoicetobeapproved: null
};
this.processService.startProcess(processDefinitionId, name, outcome, startFormValues)
  .subscribe( (processInstance: ProcessInstance) => {
  console.log('ProcessInstance: ', processInstance);
}, error => {
  console.log('Error: ', error);
});

A ProcessInstance object is returned for a successfully started process:

businessKey: null
ended: null
graphicalNotationDefined: true
id: "75001"
name: "Sample Invoice Process"
processDefinitionCategory: "http://www.activiti.org/processdef"
processDefinitionDeploymentId: "18"
processDefinitionDescription: "This is a simple invoice approval process that allows a person to assign a dedicated approver for the the invoice. It will then be routed to the Accounting department for payment preparation. Once payment is prepared the invoice will be stored in a specific folder and an email notification will be sent."
processDefinitionId: "InvoiceApprovalProcess:2:21"
processDefinitionKey: "InvoiceApprovalProcess"
processDefinitionName: "Invoice Approval Process"
processDefinitionVersion: 2
startFormDefined: false
started: Thu Nov 09 2017 08:15:37 GMT+0000 (GMT) {}
startedBy: {id: 1, firstName: null, lastName: "Administrator", email: "admin@app.activiti.com"}
tenantId: "tenant_1"
variables:
    0: {name: "approver", value: null}
    1: {name: "companyemail", type: "string", value: "someone@acme.com"}
    2: {name: "initiator", type: "string", value: "1"}
    3: {name: "invoicetobeapproved", value: null}

We can see here that the form field values have been converted to process variables.

To start the process with process variables instead of form field values do:

const processDefinitionId = 'InvoiceApprovalProcess:2:21';
const name = 'Sample Invoice Process (Var)';
const variables: ProcessInstanceVariable[] = [
  {name: 'approver', value: 'admin@app.activiti.com'},
  {name: 'companyemail', value: 'someone@acme.com'},
  {name: 'invoicetobeapproved', value: null},
  {name: 'sampleVar', value: 'hello'}
];
this.processService.startProcess(processDefinitionId, name, null, null, variables)
  .subscribe( (processInstance: ProcessInstance) => {
  console.log('ProcessInstance: ', processInstance);
}, error => {
  console.log('Error: ', error);
});

If you want to start a process that has no start form and no process variables, then do:

const processDefinitionId = 'SimpleProcess:1:2';
const name = 'Sample Process';
this.processService.startProcess(processDefinitionId, name)
  .subscribe( (processInstance: ProcessInstance) => {
  console.log('ProcessInstance: ', processInstance);
}, error => {
  console.log('Error: ', error);
});

cancelProcess(processInstanceId: string): Observable<void>

Cancel a process instance by passing in its process instance ID:

const processInstanceId = '75012';
this.processService.cancelProcess(processInstanceId)
  .subscribe( response => {
  console.log('Response: ', response);
}, error => {
  console.log('Error: ', error);
});

The response is just null if the process instance was cancelled successfully. Once a Process Instance is cancelled it will show up under processes with status completed.

You typically get the processInstanceId when you start a process. It is then contained in the ProcessInstance.id response.

createOrUpdateProcessInstanceVariables(processDefinitionId: string, variables: ProcessInstanceVariable[]): Observable<ProcessInstanceVariable[]>

Create or update variables for a Process Instance:

const processInstanceId = '75001';
const variables: ProcessInstanceVariable[] = [
  {name: 'sampleVar1', value: 'hello'},
  {name: 'sampleVar2', value: 'bye'}
];
this.processService.createOrUpdateProcessInstanceVariables(processInstanceId, variables)
  .subscribe( response => {
  console.log('Response: ', response);
}, error => {
  console.log('Error: ', error);
});

The response is an array of the successfully created ProcessInstanceVariable:

Response:  
    0: {name: "sampleVar1", type: "string", value: "hello", scope: "global"}
    1: {name: "sampleVar2", type: "string", value: "bye", scope: "global"}

If a variable already exist, then its value will be updated.

Note. you need to pass in a Process Instance ID here, not a Process Definition ID.

deleteProcessInstanceVariable(processDefinitionId: string, variableName: string): Observable<void>

Delete a variable for a Process Instance:

const processInstanceId = '75001';
const variableName = 'sampleVar1';
this.processService.deleteProcessInstanceVariable(processInstanceId, variableName)
  .subscribe( response => {
  console.log('Response: ', response);
}, error => {
  console.log('Error: ', error);
});

The response will be null if the variable was successfully deleted from the Process Instance.

Note. you need to pass in a Process Instance ID here, not a Process Definition ID.

getProcessInstanceVariables(processDefinitionId: string): Observable<ProcessInstanceVariable[]>

Get all the variables for a Process Instance:

const processInstanceId = '75001';
this.processService.getProcessInstanceVariables(processInstanceId)
  .subscribe( (procVars: ProcessInstanceVariable[]) => {
  console.log('procVars: ', procVars);
}, error => {
  console.log('Error: ', error);
});

The response is an array of ProcessInstanceVariable:

procVars:  
    0: {name: "approver", scope: "global", value: null, valueUrl: null}
    1: {name: "companyemail", scope: "global", value: "someone@acme.com", valueUrl: null}
    2: {name: "initiator", scope: "global", value: "1", valueUrl: null}
    3: {name: "sampleVar2", scope: "global", value: "bye", valueUrl: null}
    4: {name: "invoicetobeapproved", scope: "global", value: null, valueUrl: null}
    5: {name: "invoiceFileName", scope: "global", value: " - [UNKNOWN]", valueUrl: null}

Note. you need to pass in a Process Instance ID here, not a Process Definition ID.

getProcessDefinitions(appId?: number): Observable<ProcessDefinitionRepresentation[]>

Get Process Definitions associated with a Process App:

const processAppId = 2;
this.processService.getProcessDefinitions(processAppId)
  .subscribe( (procDefs: ProcessDefinitionRepresentation[]) => {
  console.log('ProceDefs: ', procDefs);
}, error => {
  console.log('Error: ', error);
});

The response is an array of ProcessDefinitionRepresentation objects looking like in this example:

0:
    category: "http://www.activiti.org/processdef"
    deploymentId: "18"
    description: "This is a simple invoice approval process that allows a person to assign a dedicated approver for the the invoice. It will then be routed to the Accounting department for payment preparation. Once payment is prepared the invoice will be stored in a specific folder and an email notification will be sent."
    hasStartForm: true
    id: "InvoiceApprovalProcess:2:21"
    key: "InvoiceApprovalProcess"
    metaDataValues: []
    name: "Invoice Approval Process"
    tenantId: "tenant_1"
    version: 2

If you wanted a list of all available process definitions call the method without specifying the process application ID:

this.processService.getProcessDefinitions()
  .subscribe( (procDefs: ProcessDefinitionRepresentation[]) => {
  console.log('ProceDefs: ', procDefs);
}, error => {
  console.log('Error: ', error);
});

getProcessInstances(requestNode: ProcessFilterParamRepresentationModel, processDefinitionKey?: string): Observable<ProcessInstance[]>

Get Process Instances for passed in filter and optionally Process Definition:

const processDefKey = 'InvoiceApprovalProcess';
const filterRunningAsc = new ProcessFilterParamRepresentationModel({
'state': 'running',
'sort': 'created-asc',
});
this.processService.getProcessInstances(filterRunningAsc, processDefKey)
  .subscribe( (processInstances: ProcessInstance[]) => {
  console.log('Process Instances: ', processInstances);
}, error => {
  console.log('Error: ', error);
});

The response is an array of ProcessInstance objects as in this example:

    0: {id: "7501", name: "Invoice Approval Process - October 9th 2017", businessKey: null, processDefinitionId: "InvoiceApprovalProcess:3:2511", tenantId: "tenant_1", …}
    1: {id: "7520", name: "Invoice Approval Process - October 9th 2017", businessKey: null, processDefinitionId: "InvoiceApprovalProcess:2:21", tenantId: "tenant_1", …}
    2: {id: "8206", name: "Invoice Approval Process - October 9th 2017", businessKey: null, processDefinitionId: "InvoiceApprovalProcess:2:21", tenantId: "tenant_1", …}
    3: {id: "8302", name: "Invoice Approval Process - October 9th 2017", businessKey: null, processDefinitionId: "InvoiceApprovalProcess:2:21", tenantId: "tenant_1", …}
    4: {id: "11337", name: "Invoice Approval 2 started from ADF client", businessKey: null, processDefinitionId: "InvoiceApprovalProcess:2:21", tenantId: "tenant_1", …}
    5: {id: "11437", name: "Invoice Approval Process - October 10th 2017", businessKey: null, processDefinitionId: "InvoiceApprovalProcess:2:21", tenantId: "tenant_1", …}
    6: {id: "67143", name: "Sample Invoice Approval 2017-10-26", businessKey: null, processDefinitionId: "InvoiceApprovalProcess:5:62514", tenantId: "tenant_1", …}
    7: {id: "75001", name: "Sample Invoice Process", businessKey: null, processDefinitionId: "InvoiceApprovalProcess:2:21", tenantId: "tenant_1", …}

You can also narrow down the search via other properties in the ProcessFilterParamRepresentationModel, such as processDefinitionId and appDefinitionId. The number of Process Instances that are returned can be controlled with the page and size properties.

getProcessTasks(processInstanceId: string, state?: string): Observable<TaskDetailsModel[]>

Get Task Instances for passed in Process Instance, optionally filter by task state:

const processInstanceId = '75001';
this.processService.getProcessTasks(processInstanceId)
  .subscribe( (taskInstances: TaskDetailsModel[]) => {
  console.log('Task Instances: ', taskInstances);
}, error => {
  console.log('Error: ', error);
});

The response is an array of TaskDetailsModel objects as in this example:

{
    "size":1,
    "total":1,
    "start":0,
    "data":[
        {"id":"75010",
        "name":"Approve Invoice  - [Invoice 123]",
        "description":null,
        "category":null,
        "assignee":{"id":1,"firstName":null,"lastName":"Administrator","email":"admin@app.activiti.com"},
        "created":"2017-11-09T08:15:37.427+0000",
        "dueDate":null,
        "endDate":null,
        "duration":null,
        "priority":50,
        "parentTaskId":null,
        "parentTaskName":null,
        "processInstanceId":"75001",
        "processInstanceName":null,
        "processDefinitionId":"InvoiceApprovalProcess:2:21",
        "processDefinitionName":"Invoice Approval Process",
        "processDefinitionDescription":"This is a simple invoice approval process that allows a person to assign a dedicated approver for the the invoice. It will then be routed to the Accounting department for payment preparation. Once payment is prepared the invoice will be stored in a specific folder and an email notification will be sent.",
        "processDefinitionKey":"InvoiceApprovalProcess",
        "processDefinitionCategory":"http://www.activiti.org/processdef",
        "processDefinitionVersion":2,
        "processDefinitionDeploymentId":"18",
        "formKey":"8",
        "processInstanceStartUserId":null,
        "initiatorCanCompleteTask":false,
        "adhocTaskCanBeReassigned":false,
        "taskDefinitionKey":"approveInvoice",
        "executionId":"75001",
        "memberOfCandidateGroup":false,
        "memberOfCandidateUsers":false,
        "managerOfCandidateGroup":false
        }
        ]
}

You can also filter by task state, which can be active or completed:

const processInstanceId = '75001';
const taskState = 'active';
this.processService.getProcessTasks(processInstanceId, taskState)
  .subscribe( (taskInstances: TaskDetailsModel[]) => {
  console.log('Task Instances: ', taskInstances);
}, error => {
  console.log('Error: ', error);
});

fetchProcessAuditJsonById(processId: string): Observable<any>

Fetch Process Audit log as JSON for a Process Instance ID:

const processInstanceId = '75001';
this.processService.fetchProcessAuditJsonById(processInstanceId)
  .subscribe( auditJson => {
  console.log('Process Audit: ', auditJson);
}, error => {
  console.log('Error: ', error);
});

The response is JSON object with the Process Instance audit log:

{
  "processInstanceId": "75001",
  "processInstanceName": "Sample Invoice Process",
  "processDefinitionName": "Invoice Approval Process",
  "processDefinitionVersion": "2",
  "processInstanceStartTime": "Thu Nov 09 08:15:37 GMT 2017",
  "processInstanceEndTime": null,
  "processInstanceDurationInMillis": null,
  "processInstanceInitiator": " Administrator",
  "entries": [
    {
      "index": 1,
      "type": "startForm",
      "selectedOutcome": null,
      "formData": [
        {
          "fieldName": "Approver",
          "fieldId": "approver",
          "value": ""
        },
        {
          "fieldName": "Company Email",
          "fieldId": "companyemail",
          "value": "someone@acme.com"
        },
        {
          "fieldName": "Invoice to be approved",
          "fieldId": "invoicetobeapproved",
          "value": ""
        }
      ],
      "taskName": null,
      "taskAssignee": null,
      "activityId": null,
      "activityName": null,
      "activityType": null,
      "startTime": null,
      "endTime": null,
      "durationInMillis": null
    },
    {
      "index": 2,
      "type": "activityExecuted",
      "selectedOutcome": null,
      "formData": [],
      "taskName": null,
      "taskAssignee": null,
      "activityId": "startInvoiceProcess",
      "activityName": "Start Invoice Process",
      "activityType": "startEvent",
      "startTime": "Thu Nov 09 08:15:37 GMT 2017",
      "endTime": "Thu Nov 09 08:15:37 GMT 2017",
      "durationInMillis": 37
    },
    {
      "index": 3,
      "type": "activityExecuted",
      "selectedOutcome": null,
      "formData": [],
      "taskName": null,
      "taskAssignee": null,
      "activityId": "approveInvoice",
      "activityName": "Approve Invoice",
      "activityType": "userTask",
      "startTime": "Thu Nov 09 08:15:37 GMT 2017",
      "endTime": null,
      "durationInMillis": null
    },
    {
      "index": 4,
      "type": "taskCreated",
      "selectedOutcome": null,
      "formData": [],
      "taskName": "Approve Invoice  - [UNKNOWN]",
      "taskAssignee": " Administrator",
      "activityId": null,
      "activityName": null,
      "activityType": null,
      "startTime": "Thu Nov 09 08:15:37 GMT 2017",
      "endTime": null,
      "durationInMillis": null
    }
  ],
  "decisionInfo": {
    "calculatedValues": [],
    "appliedRules": []
  }
}

fetchProcessAuditPdfById(processId: string): Observable<Blob>

Fetch Process Audit log as a PDF for a Process Instance ID:

const processInstanceId = '75001';
this.processService.fetchProcessAuditPdfById(processInstanceId)
  .subscribe( auditPdf => {
  console.log('Process Audit log BLOB: ', auditPdf);
}, error => {
  console.log('Error: ', error);
});

The response is a BLOB as follows:

Process Audit log BLOB:  Blob {size: 124511, type: "text/xml"}