Provisioning Flows

1. Overview

The Provision Portal runs every provisioning operation as a Business Process Model and Notation (BPMN) process. The Flowable engine executes these processes. The portal has four provisioning flows:

Each step of a flow writes a numeric status code. The Status Codes Reference lists every code.

Each flow page has a flow diagram. The diagrams show the same steps and status codes as the BPMN files in src/main/resources/processes/. If a diagram and a BPMN file differ, the BPMN file is correct.

2. Flows and Entry Points

Flow BPMN process Started by

Input Flow

  • provisioningStarter in provisioningStarter.bpmn

  • inputFlowV3 in inputFlowV3.bpmn, once for each CPE

  • Single device tab, Submit: PUT /ui/provision

  • Multiple device tab, Submit: PUT /ui/provision/multiple

  • REST: POST /provision/from-request-data, POST /provision/from-xml-file-data, POST /provision/from-csv-file-data

  • SOAP: ProvisioningForDevice, ProvisioningForDevices, ProvisioningForExternalContent

ACS Event Flow

deviceEventMonitorProcess in acsEventFlowV3.bpmn

  • REST: POST /device-event

  • SOAP: DeviceEventMonitor

Deactivate Service Flow

deactivateServiceFlow in deactivateServiceFlow.bpmn

  • Deactivate service tab, Submit: PUT /ui/provision/deactivate

  • REST: POST /service/deactivate

  • SOAP: RemoveServices

Replace CPE Flow

ReplaceCPEProcess in replaceCPE.bpmn

  • Replace device tab: PUT /ui/provision/replace-cpe

  • REST: POST /replace-cpe

  • SOAP: ReplaceCPE

REST paths are relative to the application context /prov-portal. The SOAP service is at /prov-portal/soap/ProvWS. For the full API, see API & Integration.

Some requests return the Batch ID at once and continue in the background:

  • ProvisioningForDevices

  • ProvisioningForExternalContent

  • POST /provision/from-xml-file-data and POST /provision/from-csv-file-data

  • the Multiple device tab

All other requests wait for the end of the flow and return its result.

2.1. Sub-processes

The main processes call separate BPMN processes for repeated steps:

BPMN file Purpose

inputFlowV3CreateServiceObject.bpmn

Input Flow: creates an object with FTAddObject

inputFlowV3UpdateServiceObject.bpmn

Input Flow: sets the parameters of an existing object instance

inputFlowV3ProcessServiceSubObjects.bpmn

Input Flow: processes the sub-objects of the current object

acsEventFlowV3CreateObjectFromEvent.bpmn, acsEventFlowV3UpdateObjectFromEvent.bpmn, acsEventFlowV3ProcessServiceSubObjects.bpmn, saveObjectsProcess.bpmn

ACS Event Flow: the same object steps

inputFlowV3RetrieveTaskInfo.bpmn, acsEventFlowV3RetrieveTaskInfo.bpmn, deactivateServiceFlowRetrieveTaskInfo.bpmn, replaceCPERetrieveTaskInfo.bpmn

All flows: poll the task status, see Waiting for Task Results

3. Batch Processing

provisioningStarter reads the request and runs the Input Flow for each CPE of the request. Two settings in Configuration.xml select the processing mode: <multithreading> and <numberOfMultipleThreads>.

Mode Condition Behaviour

Sequential

<multithreading> is false

The flow provisions the CPEs one after another.

Parallel

<multithreading> is true. <numberOfMultipleThreads> is equal to or greater than the number of CPEs.

The flow provisions all CPEs at the same time.

Grouped

<multithreading> is true. The request has more CPEs than <numberOfMultipleThreads>.

The flow splits the CPEs into groups of <numberOfMultipleThreads>. The CPEs of a group run in parallel. The groups run one after another.

4. Common Options

The request options change the path through the flows. On the Single device tab, these options are the General Options.

Option Effect on the flow

Delete previous

First, the flow deletes the CPE records in the provision database (provision DB). Then the flow saves the new data. Later, the flow also removes the CPE provisioning data from the ACS with FTRemoveCPEProvisionData.

Current only

Selected: the flow uses only the data of the current request. Not selected: the flow also uses the data in the provision DB for this CPE.

Reprovision, Secondary provision

The two options set the reprovision flag. The flow sends this flag with every FTSetDeviceParameters, FTAddObject and FTRPCInvoke call. See the values below.

Reboot

The flow reboots the CPE with FTRPCInvoke at the end.

Domain

If the request has a domain, the flow calls FTSetCPEDomain.

<createDevice>

A setting in Configuration.xml. true: if the ACS does not have the CPE, the flow creates the CPE with FTCreateDevice. The request must contain the OUI and the Product Class. false: the flow stores the data. The data waits for the CPE to register with the ACS.

The reprovision flag has three values:

Value Meaning

0

You select neither Reprovision nor Secondary provision. The ACS applies the values one time.

1

You select Reprovision. The ACS applies the values again on every 0 BOOTSTRAP event.

2

You select Secondary provision. The ACS applies the values on every 0 BOOTSTRAP event. The ACS creates no tasks now.

With flag 2, the flow does not wait for task results. The flow also cannot process an object with a specific instance.

5. CPE Identification

The flow identifies a CPE by its serial number (SN) or by the MAC address of its WAN connection.

  • SN: the flow searches the ACS for the SN.

  • MAC address: the flow gets the SN with FTFindCPEByWANMAC.

If the ACS does not have the CPE yet, the flow stores the data under the MAC address. When the CPE registers, the ACS Event Flow adds the SN to these records.

6. Waiting for Task Results

FTSetDeviceParameters, FTAddObject and FTRPCInvoke create tasks in the ACS. Each call returns a transaction ID. If the CPE is online, the flow polls FTGetTransactionStatus with this transaction ID. The polling stops when no task is pending.

  • All tasks completed: the step succeeds.

  • A task failed, or the ACS rejected a task: the step fails. The DebugLog gets the fault of each parameter.

  • A task is still pending after the timeout: the step fails with a timeout status.

The TIMEOUT environment variable sets the timeout in seconds. The default is 60.

The TRANSACTION_DELAY environment variable sets an extra wait in milliseconds. The default is 1000. After the first completed task, the flow waits for this time. Then the flow accepts the result.

If the CPE is offline, the flow does not poll. The tasks stay in the ACS. The ACS runs the tasks when the CPE connects.

7. Status Codes and Logs

Each step writes its status code to three places:

  • the DebugLog, as <SN or MAC> <code> : <description>

  • the CustomLog, if CustomStatus.xml lists the code

  • the status record of the CPE in the batch

The last code of a CPE is its final operation code. You see this code on the Get status tab.

If an ACS call fails, the DebugLog also gets this line:

ERROR - Method '<method>' failed with error code: <code> and message: <message>

For the log files, see View Log. For every code, see Status Codes Reference.