03-api

Use this to add Company specific API stuff like the configuration of the projects within the Company.

The following structure is generated by ./helperCompany.scala init:

03-api/src
         | main/resources
         | main/scala/company/api
         |                     | CompanyApiCreator.scala          
         | test/scala/company/api

CompanyApiCreator

The Company's base class to generate the API documentation and API Clients for Postman.

Example (generated by ./helperCompany.scala init):

import camundala.api.*

trait CompanyApiCreator extends ApiCreator, ApiDsl, CamundaPostmanApiCreator:

    // override the config if needed
    protected def apiConfig: ApiConfig = CompanyApiCreator.apiConfig

    lazy val companyProjectVersion = BuildInfo.version
    
object CompanyApiCreator:
    lazy val apiConfig = ApiConfig(companyName = "mycompany")
end CompanyApiCreator

ApiConfig

You can customize the API Configuration.

Here an example:

import camundala.api.ApiConfig

lazy val apiConfig: ApiConfig =
  ApiConfig("mycompany")
    .withTenantId("mycompany")
    .withDocBaseUrl(s"http://mycompany.ch/bpmnDocs")
    .withJiraUrls("COM" -> "https://issue.mycompany.ch/browse")

Default ApiConfig

This is the default Configuration:

// your company name like 'mycompany'
companyName: String,
// define tenant if you have one - used for the Postman OpenApi
tenantId: Option[String] = None,
// contact email / phone, if there are questions
contact: Option[Contact] = None,
// REST endpoint (for testing API)
endpoint: String = "http://localhost:8080/engine-rest",
// Base Path of your project (if changed - all doc paths will be adjusted)
basePath: os.Path = os.pwd,
// If you work with JIRA, you can add matchers that will create automatically URLs to JIRA Tasks
jiraUrls: Map[String, String] = Map.empty,
// Configure your project setup
projectsConfig: ProjectsConfig = ProjectsConfig(),
// Configure your template generation
modelerTemplateConfig: ModelerTemplateConfig = ModelerTemplateConfig(),
// The URL of your published documentations
// s"http://myCompany/bpmnDocs"
docBaseUrl: Option[String] = None,
// Path, where the Git Projects are cloned - for dependency check.
// the default is for the structure: dev-myCompany/projects/myProject
tempGitDir: os.Path = os.pwd / os.up / os.up / "git-temp"

ProjectsConfig

You can configure your projects.

Here an example:

import camundala.api.*

lazy val projectsConfig = ProjectsConfig(
  // Path to your ApiProjectConf - default is os.pwd / PROJECT.conf
  projectConfPath = os.rel / "src" / "main" / "resources" / "myproject.conf",
  // grouped configs per GitRepos - so it is possible to use projects from different Repos
  perGitRepoConfigs = Seq(myCompanyGitRepoConfig)
)

lazy val myCompanyGitRepoConfig = ProjectsPerGitRepoConfig(
  // Base URL for the Git Repos
  // The pattern must be $cloneBaseUrl/$projectName.git
  cloneBaseUrl = "ssh://git@mycompany.com:2222/myrepo",
  // Definition of the projects
  projects = myProjects
)

lazy val myProjects = Seq(`mycompany-services`, `mycompany-finances`, `mycompany-employees`)

lazy val `mycompany-services` = ProjectConfig(
  // Name of the project
  name = "mycompany-services",
  // you can group your projects - for better overview
  group =  services,
  // the color of your project - for better overview and visualization in the BPMN diagrams
  color = "blue"
)

lazy val `mycompany-finances` = ???
lazy val `mycompany-employees` = ???
lazy val services = ProjectGroup(
  name = "services",
  // line color
  color = "purple",
  fill = "#ddd"
)

All other information is taken automatically from the ApiProjectConf.

Standard Features:

With the API Creator you get a lot of features out of the box.

README

If you have a read me in your base path (config.basePath / "README.md), we integrate it automatically in the documentation - as a visible part.

CHANGELOG

If you have a change log in your base path (config.basePath / "CHANGELOG.md), we integrate it automatically in the documentation - as a collapsed part.

General Variables

General variables that are supported in any Process- and/or ExternalTask-Worker are documented - in a collapsed part. By default, the following Variables are supported:

enum InputParams:
  // mocking
  case servicesMocked
  case mockedWorkers
  case outputMock
  case outputServiceMock
  // mapping
  case manualOutMapping
  case outputVariables
  case handledErrors
  case regexHandledErrors
  // authorization
  case impersonateUserId
  // ..
end InputParams

That expects that your implementation can handle these variables.

If you are using our Workers they are supported out of the box!

If you only want to support some of them, you can override them:

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

Jira Tickets

We replace configured JIRA Ticket pattern with its URL.

Configuration:

  override protected def apiConfig: ApiConfig =
    super.apiConfig
      .withJiraUrls(JIRA_PROJECT -> JIRA_URL)

Now in the Change Log all occurrences of the regex JIRA_PROJECT-(\\d+) (-> JIRA_TICKET) will be replaced with [JIRA_TICKET]($url/JIRA_TICKET). In the generated documentation this is a link to the according Jira ticket.

BPMN diagrams

BPMN- and DMN diagrams are integrated in the documentation.

They are referenced in the OpenApi.html and can be opened directly from there. There are 3 ways:

  1. As an image in the documentation
  2. As a link to download the BPMN-/ DMN-diagram
  3. As SVG image to show the diagram in the browser (you can zoom in and out)

This is only working if you upload your BPMN- and DMN-diagrams to a Web server (via WebDAV).

Project dependencies

To know where your process is used and what processes your process is using, is very helpful. It works for BPMNs and DMNs.

Camundala will clone or update all configured projects:

ProjectsConfig.perGitRepoConfigs/$project.git into ApiConfig.tempGitDir

for example:

https://github.com/mycompany/mycompany-myproject.git -> ../../git-temp/mycompany-myproject.

It creates bullet lists grouped by projects:

Used in 2 Project(s)

Uses 1 Project(s)

Used Dependency Resolution

For each Process (BPMN):

Uses Dependency Resolution

For each Process (BPMN or DMN):

The BPMNs and DMNs are resolved by their ids. So it is essential that the ids are unique.

This is done by following naming conventions. You can easily enforce that by using the provided generators, see Generate Process/-Elements.