General Concerns

(General Variables)

To avoid a lot of boilerplate in your Input Objects, we define a list of input variables we handle by default.

We generate a description with the API Documentation under General Variables.

• camundala-api:

  • Creates the documentation of these variables, including example.
  • For mocking, it will generate a concrete example in each Process or ServiceProcess.

• camundala-simulation:

  • Adds them, if defined to call the Camunda's REST API.

• camundala-worker:

  • Part of the implementation.

You can override the list of variables, you support in your ApiProjectCreator, like

import camundala.bpmn.InputParams.*

override def supportedVariables: Seq[InputParams] = Seq(
    servicesMocked,
    outputMock,
    outputServiceMock,
    handledErrors,
    regexHandledErrors,
    impersonateUserId
  )

Mocking

This looks a bit strange, that mocking is at the domain level. However, it turns out that this is quite helpful:

• API Documentation: You see if a process provides Mocking, and/or if it is possible to mock certain sub processes.
• Simulation: You can simply mock sub processes and workers.
• Postman Requests: You can manipulate with mocks the path taken in the process (even on production).

We have four ways to mock. Each possibility is done with a dedicated Process Variable.

1. Services mocked

• Variable: servicesMocked: Boolean - default: false

In a process, this mocks every ServiceTask (ServiceWorker), with the serviceMock (MockedServiceResponse[ServiceOut]).

2. Mocked Workers

• Variable: mockedWorkers: Seq[String] - default: Seq.empty

In a process, this mocks the SubProcesses and ServiceTasks, if their topicName or processName is in this list.

Processes must have an InitWorker and you need to add an In Mapping in the BPMN!

3. Mocked Output

• Variable: outputMock: Option[Out] - default: None

A Process or a Worker, can be mocked with its Out object.

Processes must have an InitWorker!

4. Mocked Service Output

• Variable: outputServiceMock: Option[MockedServiceResponse[ServiceOut]] - default: None

A ServiceWorker, can be mocked with its ServiceOut object.

This allows you also to mock failures in the Service, e.g. MockedServiceResponse.error(404).

Mocking Input (outputMock & outputServiceMock)

We define specific Mocks of a Process in its Input Class (In).

  case class In(
                 //..
                 mocks: Option[Mocks] = None
               )

For better readability we put all Mocks in a separate case class:

  case class Mocks(
                    @description(serviceOrProcessMockDescr(GetAccount.Out()))
                    getAccountMock: Option[GetAccount.Out] = None,
                    @description(serviceOrProcessMockDescr(GetAccount.serviceMock))
                    getServiceAccountMock: Option[MockedServiceResponse[GetAccount.ServiceOut]] = None,
                  )

This class contains all mocks as optional variables.

• In the BPMN you map the mocks to the according outputMock or outputServiceMock.

  • getAccountMock -> outputMock
  • getServiceAccountMock -> outputServiceMock

Process Configuration

The configuration of a process is also part of the Input object (In), and so part of the domain specification.

A like the Mocks this has these advantages:

• API Documentation: You see if there are technical variables that you can adjust. E.g. Timers etc.
• Simulation: You can simply set a Timer to 0, to also test Timers.
• Postman Requests: A Business Analyst can test the process also, without waiting until a Timer is due.

We define specific Mocks of a Process in its Input Class (In).

  case class In(
                 //..
                 config: Option[InConfig] = None,
               )

For better readability we put all Configurations in a separate case class:

  case class InConfig(
                       @description("Timer to wait....")
                       waitForInput: String = "PT2H"
                     )

The class contains all variables with its default values.

Mapping

By default, all output variables (Out) of a Worker are on the process (External Task completion).

To reduce the variables you have two possibilities, that also can be combined:

1. Filter Output Variables

• Variable: outputVariables: Seq[String] - default: Seq.empty

You can filter the Output with a list of variable names you are interested in. This list may include all variables from the output (Out).

2. Manual Output Mapping

• Variable: manualOutMapping: Boolean - default: false

This will complete the External Task only with local output variables. And you must do the output mapping manually in the BPMN.

Exception Handling

To handle an Exception in a Worker, we can do the following:

1. List of Error Codes

• Variable: handledErrors: Seq[String] - default: Seq.empty

To handle Errors in a ServiceTask, you need to define a list of error codes. If an error has this error code, it will complete with a BpmnError, instead a Failure.

If you want to handle all Errors, you can use CatchAll instead listing all possible error codes.

2. List of Error Messages

• Variable: regexHandledErrors: Seq[String] - default: Seq.empty

If the error code is not enough, you can also add a list of regex expressions, to filter the Errors you handle.

For example, you want to handle a 400 error, but only if the message contains bad response.

Authorization

Impersonate User

• Variable: impersonateUserId: Option[String] - default: None

User-ID or Correlation-ID of a User that should be taken to authenticate to the services. This must be supported by your implementation.

It is helpful if you have Tokens that expire, but long-running Processes.

Validation

The Validation is handled by all Workers and no additional variables are needed.

The following objects are handled:

• Input Variables (In)
• Service Output Variables (Service Output Body ServiceOut)