usage

Usage

Executing Solicitor

Solicitor is a standalone Java (Spring Boot) application. Prerequisite for running it is an existing Java runtime environment (Java Version: 17 - 25). If you do not yet have the Solicitor executable JAR (solicitor.jar) you need to build it as given on the project GitHub homepage https://github.com/devonfw/solicitor .

Solicitor is executed with the following command:

java -jar solicitor.jar -c <configfile>

where <configfile> is to be replaced by the location of the Project Configuration File.

To get a first idea on what Solicitor does you might call

java -jar solicitor.jar -c classpath:samples/solicitor_sample.cfg

This executes Solicitor with default configuration on its own list of internal components and produces sample output.

To get an overview of the available command line options use

java -jar solicitor.jar -h

Addressing of resources

For unique addressing of resources to be read (configuration files, input data, rule templates and decision tables) Solicitor makes use of the Spring ResourceLoader functionality, see https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/core.html#resources-resourceloader . This allows to load from the classpath, the filesystem or even via http get.

If you want to reference a file in the filesystem you need to write it as follows: file:path/to/file.txt

Note that this only applies to resources being read. Output files are addressed without that prefix.

Project Configuration File

The project configuration of Solicitor is done via a configuration file in JSON format. This configuration file defines the engagements and applications master data, configures the readers for importing component and license information, references the business rules to be applied and defines the exports to be done.

The config file has the following skeleton:

{
  "version" : 1,
  "comment" : "Sample Solicitor configuration file",
  "engagementName" : "devonfw", (1)
  .
  .
  .
  "applications" : [ ... ], (2)
  "rules" : [ ... ],  (3)
  "writers" : [ ... ], (4)
  "additionalWriters" : [ ...] (5)
}

The leading data defines the engagement master data, see Header and Engagement Master Data
applications defines the applications within the engagement and configures the readers to import the component/license information, see Applications
rules references the rules to apply to the imported data, see Business Rules
writers configures how the processed data should be exported, see Writers and Reporting
additionalWriters defines optional additional project specific writers without overwriting already defined writers, see Writers and Reporting

Note	The following section describes all sections of the Solicitor configuration file format. Often the configuration of `writers` and especially `rules` will be identical for projects. To facilitate the project specific configuration setup Solicitor internally provides a base configuration which contains reasonable defaults for the `rules` and `writers` section. If the project specific configuration file omits the `rules` and/or `writers` sections then the corresponding settings from the base configuration will be taken. For details see [Default Base Configuration].

Warning	If locations of files are specified within the configuration files as relative pathnames then this is always evaluated relative to the current working directory (which might differ from the location of the configuration file). If some file location should be given relative to the location of the configuration file this might be done using the special placeholder `${cfgdir}` as described in the following.

Placeholders within the configuration file

Within certain parts of the configuration file (path and filenames) special placeholders might be used to parameterize the configuration. These areas are explicitly marked in the following description.

These placeholders are available:

${project} - A simplified project name (taking the engagement name, removing all non-word characters and converting to lowercase).
${cfgdir} - If the config file was loaded from the filesystem this denotes the directory where the config file resides, . otherwise. This can be used to reference locations relative to the location of the config file.

Header and Engagement Master Data

The leading section of the config file defines some metadata and the engagement master data.

  "version" : 1, (1)
  "comment" : "Sample Solicitor configuration file", (2)
  "engagementName" : "devonfw", (3)
  "engagementType" : "INTERN", (4)
  "clientName" : "none", (5)
  "goToMarketModel" : "LICENSE", (6)
  "contractAllowsOss" : true, (7)
  "ossPolicyFollowed" : true, (8)
  "customerProvidesOss" : false, (9)

version of the config file format (currently needs to be 1)
is a free text comment (no further function at the moment)
the engagement name (any string)
the engagement type; possible values: INTERN, EXTERN
name of the client (any string)
the go-to-market-model; possible values: LICENSE
does the contract explicitly allow OSS? (boolean)
is the companies OSS policy followed? (boolean)
does the customer provide the OSS? (boolean)

Applications

Within this section the different applications (=deliverables) of the engagement are defined. Furthermore, for each application at least one reader needs to be defined which imports the component and license information.

 "applications" : [ {
    "name" : "Devon4J", (1)
    "releaseId" : "3.1.0-SNAPSHOT", (2)
    "sourceRepo" : "https://github.com/devonfw/devon4j.git", (3)
    "programmingEcosystem" : "Java8", (4)
    "reportingGroups" : [ (5)
        "default",
        "web app"
    ],
    "readers" : [ { (6)
      "type" : "maven", (7)
      "source" : "classpath:samples/licenses_devon4j.xml", (8) (13)
      "usagePattern" : "DYNAMIC_LINKING", (9)
      "modified" : false, (10)
      "packageType" : "maven", (11)
      "configuration" : { (12)
        .
        .
        .
      }
    } ]
  } ],

The name of the application / deliverable (any string)
Version identifier of the application (any string)
URL of the source repo of the application (string; should be an URL)
programming ecosystem (any string; e.g. Java8; Android/Java, iOS / Objective C)
optional definition of the reporting groups this Application will be assigned to; if not defined then the Application will be assigned to the reporting group default; see [Reporting Groups]
multiple readers might be defined per application
the type of reader; for possible values see [Reading License Information with Readers]
location of the source file to read (ResourceLoader-URL)
usage pattern; possible values: DYNAMIC_LINKING, STATIC_LINKING, STANDALONE_PRODUCT; see description below in Usage Patterns
indicates if the code of ApplicationComponents read by this reader was modified; see hints on usage below in Handling of Modified OSS Components; the parameter is optional and will default to false
packageType: type of the packages in the input data. Must be a valid packageUrl type (see https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst). Relevant when using the CSV reader.
configuration: optional configuration parameters for the Reader, given as name/value pairs.
placeholder patterns might be used here

Usage Patterns

The usage pattern describes how the ApplicationComponents (libraries, packages) which are read in via the Reader are linked (in)to the Applications executable. The kind of linking might affect the legal evaluation of the license compliance.

DYNAMIC_LINKING - The component is dynamically linked and is separated/separable from the rest of the executable and might be exchanged. This specifically covers two cases:
- The component is not included in the executable but is either already existing on the target system or is deployed separately from the executable. Exchanging the component can be done by replacing the component without touching the executable / other components of the application.
- The component is included in the executable and is linked into the executable in a way that allows it to clearly distinguish it from the other components. It is possible to separate the component from the rest of the executable and to replace the component with a modified version of the component just using common tooling.
STATIC_LINKING - The component is linked into the executable in a way that makes it (practically) impossible to separate it from the rest of the executable. In case that this single component needs to be replaced the linking process has to be re-executed based on the (unlinked) components. De facto this means that separating and/or exchanging the single components with only the executable at hand is practically impossible.
STANDALONE_PRODUCT - The component is not linked to other components. It is executed in its own process.

Warning	The semantics of `DYNAMIC_LINKING` and `STATIC_LINKING` within Solicitor might differ from the common software engineers technical understanding of dynamic and static linking. The main characteristics important in this context are given above. As the legal evaluation of OSS license compliance might rely on the correct specification of the usage pattern you should consult the person being responsible for the legal evaluation if you are not sure about the right value. (Or in case that you are responsible for the legal evaluation: Make sure that the understanding of the possible usage pattern values corresponds to the legal evaluation rules you have defined.)

Filtering of components within Readers

Under certain conditions it might be useful to only process a subset of the components given in a Reader input file within Solicitor. To achieve this it is possible to define an includeFilter and/or an excludeFilter in the Reader configuration. The filters are defined as regular expressions for the PackageURL of the component:

.
.
.
{
  "type" : "maven",
  "source" : "classpath:samples/licenses_devon4j.xml",
  "usagePattern" : "DYNAMIC_LINKING",
  "packageType" : "maven",
  "configuration" : {
    "includeFilter": "pkg:maven/mygroup/.*", (1)
    "excludeFilter": "pkg:maven/mygroup/someartifact@.*" (2)
  }
}
.
.
.

includeFilter: A component will only be processed in Solicitor if the PackageURL of the component matches the given regex.
excludeFilter: A component will not be processed in Solicitor if the PackageURL of the component matches the given regex.

If both filters are defined (as in the given snippet) then a component will only be processed in Solicitor if the includeFilter regex is matched and the excludeFilter regex is not matched.

If the PackageURL of the component is not defined it will be represented as an empty string when doing the regular expression matching. (An empty/zero length regex string will match in this case.)

Deriving groupId, ArtifactId and Version from the PackageURL

If the data of components which is read via a Reader contains the coordinates groupId, artifactId and version as well as a PackageURL it might be possible that the mapping between the "coordinates" (which historically were initially defined for maven packages) and the PackageURL is not consistent to the standard mapping as used by Solicitor. By setting reader configuration property deriveCoordinatesFromPurl to true it is possible to instruct the Reader to derive the three coordinates from the PackageURL instead of directly taking them from the input file (this only works if the PackageURL is defined for the component and is one of the types which is explicitly handled within Solicitor).

.
.
.
{
  "type" : "cyclonedx",
  "source" : "classpath:samples/some_cyclonedx_sbom.xml",
  "usagePattern" : "DYNAMIC_LINKING",
  "configuration" : {
    "deriveCoordinatesFromPurl": "true"
  }
}
.
.
.

Handling of Modified OSS Components

If Open Source Components were modified this might require to comply with additional obligations when distributing. (Like distributing the modified source code or documenting the code changes.) The fact whether an ApplicationComponent was modified or not is represented in the Solicitor data model by the boolean property ossModified. This flag by default is set to false when importing the data of ApplicationComponents using Readers. By setting the optional Reader configuration parameter modified to true the flag ossModified will be set to true for all ApplicationComponents imported by this Reader.

Using the above explained Filtering of components within Readers allows to set ossModified to different values for ApplicationComponents read from the same input file.

.
.
.
"readers" : [ {
  "type" : "maven",
  "source" : "file:${cfgdir}/input/licenses.xml",
  "usagePattern" : "DYNAMIC_LINKING",
  "modified" : false,
  "configuration" : {
    "excludeFilter": "pkg:maven/.*/.*@.*-MODIFIED"
  }
},{
  "type" : "maven",
  "source" : "file:${cfgdir}/input/licenses.xml",
  "usagePattern" : "DYNAMIC_LINKING",
  "modified" : true,
  "configuration" : {
    "includeFilter": "pkg:maven/.*/.*@.*-MODIFIED"
  }
} ]
.
.
.

This will set ossModified to true for all imported ApplicationComponents where the version ends in the suffix "-MODIFIED".

Note	The different readers are described in chapter [Reading License Information with Readers].

Business Rules

Business rules are executed within a Drools rule engine. They are defined as a sequence of rule templates and corresponding XLS(X) (or CSV) files which together represent decision tables.

  "rules" : [ {
    "type" : "dt", (1)
    "optional" : false, (2)
    "ruleSource" : "classpath:samples/LicenseAssignmentV2Sample.xls", (3) (9)
    "templateSource" : "classpath:com/.../rules/rule_templates/LicenseAssignmentV2.drt", (4) (9)
    "ruleGroup" : "LicenseAssignmentV2", (5)
    "description" : "setting license in case that no one was detected", (6)
    "deprecationWarnOnly" : true, (7)
    "deprecationDetails" : "This decision table should be migrated to ..." (8)
  },
  .
  .
  .
,{
    "type" : "dt",
    "optional" : false,
    "ruleSource" : "classpath:samples/LegalEvaluationSample.xls",
    "templateSource" : "classpath:com/.../rules/rule_templates/LegalEvaluation.drt",
    "ruleGroup" : "LegalEvaluation",
    "description" : "final legal evaluation based on the rules defined by legal"
  } ],

type of the rule; only possible value: dt which stands for "decision table"
if set to true the processing of this group of rules will be skipped if the XLSX/XLS/CSV with table data (given by ruleSource) does not exist; if set to false a missing XLSX/XLS/CSV table will result in program termination
location of the tabular decision table data. This might either point directly to the XLSX, XLS or CSV file or only give the resource name without suffix. In this case Solicitor will dynamically test for existing resources by appending suffixes xlsx, xls and csv.
location of the drools rule template to be used to define the rules together with the decision table data
id of the group of rules; used to reference it e.g. when doing logging
some textual description of the rule group
flag to control which level of deprecation (see [Feature Deprecation]) applies to this rule group; optional and only applicable if deprecationDetails is also defined.
optional value; if set then the use of the defined decision table is deprecated; the given string will be given as part of the log message
placeholder patterns might be used here

When running, Solicitor will execute the rules of each rule group separately and in the order given by the configuration. Only if there are no more rules to fire in a group Solicitor will move to the next rule group and start firing those rules.

Normally a project will only customize (part of) the data of the decision tables and thus will only change the ruleSource and the data in the XLSX/XLS/CSV. All other configuration (the different templates and processing order) is part of the Solicitor application itself and should not be changed by end users.

See [Working with Decision Tables] and [Standard Business Rules] for further information on the business rules.

Writers and Reporting

The writer configuration defines how the processed data will be exported and/or reported.

  "writers" : [ {
    "type" : "xls", (1)
    "templateSource" : "classpath:samples/Solicitor_Output_Template_Sample.xlsx", (2) (9)
    "target" : "OSS-Inventory-devonfw${-reportingGroup}.xlsx", (3) (9) (10)
    "description" : "The XLS OSS-Inventory document", (4)
    "enableReportingGroups" : true, (5)
    "includeDeletedRowsInDelta" : true, (6)
    "protectionPassword" : "soMePaSsWord", (7)
    "dataTables" : { (8)
      "ENGAGEMENT"  : "classpath:com/devonfw/tools/solicitor/sql/allden_engagements.sql",
      "LICENSE" : "classpath:com/devonfw/tools/solicitor/sql/allden_normalizedlicenses.sql"
    }
  } ]

type of writer to be selected; possible values: xls, velo
path to the template to be used
location of the output file
some textual description
flag which enables use of reporting groups for this writer (optional, see [Reporting Groups])
optional flag which enables the inclusion of deleted rows/records in the report if used in delta/diff mode; defaults to false; this should only be set to true if the Writer and/or used template supports appropriate rendering of such rows (e.g. using strikethrough to clearly mark them as being no longer present); also see [Writers]
optional password which controls protection of the generated report against changes; only supported for [Excel Writer]; see [Excel sheet protection against unwanted manual changes] for details
reference to SQL statements used to transform the internal data model to data tables used for reporting
placeholder patterns might be used here
for the target value special additional placeholders are available to handle reporting group information. See [Using Reporting Group Information in Report Filename].

If a writers section is defined in the project configuration then it will replace the writer configuration given in the builtin default configuration. If you want to just add additional project specific writers then you might define them in the (optional) additionalWriters section of the project configuration file. These get processed additionally to the default writers. The section additionalWriters has the same attributes as the standard writers configuration.

  "additionalWriters" : [ {
    "type" :
    ...
    "dataTables" : {
        ...
    }
  } ]

For details on the writer configuration see [Reporting and Creating output documents].

Starting a new project

To simplify setting up a new project Solicitor provides an option to create a project starter configuration in a given directory.

java -jar solicitor.jar -wiz some/directory/path

Besides the necessary configuration file this includes also empty XLSX for defining project specific rules which amend the builtin rules. Furthermore, a sample license.xml file is provided to directly enable execution of solicitor and check functionality.

This configuration then serves as starting point for project specific configuration.

Exporting the Builtin Configuration

When working with Solicitor it might be necessary to get access to the builtin base configuration, e.g. for reviewing the builtin sample rules or using builtin reporting templates as starting point for the creation of own templates.

The command

java -jar solicitor.jar -ec some/directory/path

will export all internal configuration to the given directory. This includes:

The base configuration file, which defines standard settings inherited by the Project Configuration File
The Drools Rule Templates
The builtin decision tables which are referenced in the base configuration, see [Standard Business Rules]
The SQL statements which are used for [SQL transformation and filtering]
The referenced templates for the [Velocity Writer] and [Excel Writer]

Configuration of Technical Properties

Besides the project configuration done via the above described file there are a set of technical settings in Solicitor which are done via properties. Solicitor is implemented as a Spring Boot Application and makes use of the standard configuration mechanism provided by the Spring Boot Platform which provides several ways to define/override properties.

The default property values are given in [Built in Default Properties].

In case that a property shall be overridden when executing Solicitor this can easiest be done via the command line when executing Solicitor. In case that the property value contains whitespaces it needs to be enclosed in double quotes:

java -Dsome.property.name1=value -Dsome.property.name2="another value with spaces" -jar solicitor.jar <any other arguments>

Navigation Menu

usage

Usage

Executing Solicitor

Project Configuration File

Placeholders within the configuration file

Header and Engagement Master Data

Applications

Usage Patterns

Filtering of components within Readers

Deriving groupId, ArtifactId and Version from the PackageURL

Handling of Modified OSS Components

Business Rules

Writers and Reporting

Starting a new project

Exporting the Builtin Configuration

Configuration of Technical Properties

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally