operator-user-guide.tex

% Copyright (c) 2021 ArSysOp and others
%
% This program and the accompanying materials are made available under the
% terms of the Eclipse Public License 2.0 which is available at
% https://www.eclipse.org/legal/epl-2.0/.
%
% SPDX-License-Identifier: EPL-2.0
%
% Contributors:
%     Nikifor Fedorov (ArSysOp)

\documentclass[12pt]{report}

\usepackage{color}
\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}

\usepackage{listings}
\usepackage{verbatim}

\usepackage{graphicx}
\graphicspath{{../../i/o/},{../../i/common/}}

\usepackage{hyperref}
\hypersetup{colorlinks=true,
linkcolor=black,
urlcolor=gray}

\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\lhead{\includegraphics[width=13pt]{glyph}}
\rhead{\leftmark}
\lfoot{\thepage}
\rfoot{Eclipse Passage}
\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
\renewcommand{\headrulewidth}{0.5pt}
\renewcommand{\footrulewidth}{0.5pt}

\fancypagestyle{plain}{
    \fancyhf{}
    \lhead{\includegraphics[width=13pt]{glyph}}
    \rhead{\leftmark}
    \lfoot{\thepage}
    \rfoot{Eclipse Passage}
    \renewcommand{\headrulewidth}{0.5pt}
    \renewcommand{\footrulewidth}{0.5pt}
}

\setlength{\headheight}{16pt}

\title{Eclipse Passage Operator User Guide}
\author{ArSysOp}
\date{26 June 2021}

\begin{document}

\begin{titlepage}
    \begin{center}

        \Huge
        \textbf{Eclipse Passage Operator}
        
        \vspace*{1cm}
        \Large
        \textbf{User Guide}

        \vspace{0.5cm}

        \Large
        \today

        \vfill

        \includegraphics[width=5cm]{passage}

        \vfill

        \Large
        ArSysOp
    \end{center}
\end{titlepage}

\tableofcontents
\markboth{Table of Contents}{}

\chapter*{Introduction}
\addcontentsline{toc}{chapter}{Introduction}
\markboth{Introduction}{}

\section*{Overview}
\addcontentsline{toc}{section}{Overview}

\textbf{Eclipse Passage} is a set of tools providing rich and easily adaptable capabilities to declare and control licensing constraints.
Being an open-source project under Eclipse Foundation, it is entirely developed with Java 11 by the \textit{ArSysOp} company.

This user guide contains a glossary, which gives you base understanding of terms used in Eclipse Passage and two sets of instructions: for developer, who
wants to license some features or entire application with Passage, and for operator, who wants to manage licenses and metadata with the Eclipse Passage Operator.

Happy Reading!

\section*{Contribution}
\addcontentsline{toc}{section}{Contribution}

If you found a mistake in the text or just want to improve this user guide, feel free to contribute on \href{https://github.com/eclipse-passage/passage-docs}{Github} repository.

Also we want to remind that Eclipse Passage is an open-source project, so you can always contribute to the project \href{https://github.com/eclipse-passage/passage}{itself}.

\section*{License}
\addcontentsline{toc}{section}{License}

These materials are made available under the terms of the \href{https://www.eclipse.org/legal/epl-2.0/}{Eclipse Public License 2.0}.

\chapter*{Components}
\addcontentsline{toc}{chapter}{Components}
\markboth{Components}{}

Eclipse Passage consists of three parts:

\section*{Licensing Components}
\addcontentsline{toc}{section}{Licensing Components}

Licensing Components is a set of tools you have to include in your application to be able to declare any licensing logic (For example, what to do if a correct license was not acquired by the licensing framework).
It allows you to restrict unauthorized using of a single feature, bundle or even the whole application.

\section*{Operator}
\addcontentsline{toc}{section}{Operator}

Operator client is a separate application giving you a manual control under all the licenses your product can have (both personal and floating). Also, it is required
in access cycle in order to define the product or/and features metadata and to generate keypair for license file encoding.

\section*{Floating License Server}
\addcontentsline{toc}{section}{Floating License Server}

Eclipse Passage FLS is a component implementing the Floating License Server concept. Works roughly in a way described below.

The licensee acquires (in any way) a finite number of licenses and these licenses are stored on the License Server. When an authorized user wants to use the application,
they request a license from the server, and if the license pool is not empty (in other words, there are still licenses available), the server gives user an access to the
application. When user finishes his work with the application, the license is released and can be obtained by the other authorized user.

\chapter*{Passage Operator User Guide}
\addcontentsline{toc}{chapter}{Passage Operator User Guide}
\markboth{Passage Operator User Guide}{}

\section*{Introduction}
\addcontentsline{toc}{section}{Introduction}

\subsection*{Main concepts}
\addcontentsline{toc}{subsection}{Main concepts}

The best approach to learn any existing user interface is understanding the concepts it is based on. In Eclipse Passage worldview the product licensing sequence consits of three parts:

\begin{itemize}
    \item \textbf{Definition} - on this step you define your product lines, products and all the features it has to be licensed with Eclipse Passage. Responsibility for this step usually lies on the marketers' shoulders.
    \item \textbf{Evolution} - when you defined the product and features it has, it's time to start development. New versions are being released, some functionality can be added, changed or even dropped away.
    \item \textbf{Licensing} - after you have at least one version of your product or feature released, you can start issuing licenses to your users.
\end{itemize}

These are three main steps to have your features properly licensed with Passage Operator.

\subsection*{UI Overview}
\addcontentsline{toc}{subsection}{UI Overview}

Eclipse Passage Operator's initial layout is quite simple: dashboard with all products, features, users and license plans contained in your workspace; workbench part (initially filled with welcome page),
where you you usually deal with some licensing data (E. g. you can define your features here), top toolbar with some useful wizards and controls, two buttons to issue a license.

\begin{center}
    \includegraphics[width=\textwidth]{ui}
\end{center}

\section*{How to license your product}
\addcontentsline{toc}{section}{How to license your product}

This tutorial contains three parts mapped with three licensing steps mentioned in the section above.

\subsection*{Definition}
\addcontentsline{toc}{subsection}{Definition}

First of all, we have to define what our product is. To be more concise with the reader, tutorial at all is provided with examples based on Eclipse Passage commercial version (Cordon).

Usually some products are provided separately around the same system (library or something like that). In our case ArSysOp Cordon provides a simple product line, containing three licensable components:
\begin{itemize}
    \item Cordon Access Cycle (Licensing Components)
    \item Cordon Operator (Like Passage Operator)
    \item Cordon Floating License Server
\end{itemize}

\paragraph*{Create Product Line}
\paragraph*{}

Let's open product line creation dialog by pressing the \textit{Create} button near the Products area.

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_line_create}
\end{center}

In the dialog appeared we have to choose a place, where our product line model will physically exist (as .xmi model), choose unique identifier and any beautiful name.

Remember location where your xmi files are saved. These model files can also be imported with \textit{Load} button.

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_line_dialog}
\end{center}

Press \textit{Finish} and that's it! My congratulations, you have just defined your first product line with Passage! Let's fill it with some products.

\paragraph*{Fill Product Line with Products}
\paragraph*{}

Press \textit{Show} near the Product lines count. Now you see the workbench with one defined product line and no products under it.

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_create}
\end{center}

On your product line with right click open the context menu, where you will see an option named \textit{Product}. Pressing it you define new product under the selected product line.
Let it be the Cordon Operator in our case. Fill all the required fields and optional fields if needed.

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_dialog}
\end{center}

Congratulations again! The product is now created and ready to be filled with features, which we are about to define. 

\paragraph*{Define Features}
\paragraph*{}

Let's imagine we have two licensing cases for our product:
\begin{itemize}
    \item we want to check license on start for all users
    \item we want one feature to be licensed separately - not all users who bought Cordon Operator License are allowed to use it. Let it be license usage statistics, for example.
\end{itemize}

First, we have to define a feature that will represent usage statistics collection. Press \textit{Create} button near the Features area to create Feature Set.

\begin{center}
    \includegraphics[width=0.75\textwidth]{feature_set_create}
\end{center}

And then select model file location, feature set id and name.

\begin{center}
    \includegraphics[width=0.75\textwidth]{feature_set_dialog}
\end{center}

Press \textit{Finish} and then \textit{Show} near the feature set count.

\begin{center}
    \includegraphics[width=0.75\textwidth]{feature_create}
\end{center}

Like the product under product line, create the feature under feature set with the context menu showed on right-click, then fill identifier and name fields at least and save.

\begin{center}
    \includegraphics[width=0.75\textwidth]{feature_dialog}
\end{center}

Now we successfully defined our product exceptional feature. To have our product licensed at all, we need to define another feature with \textbf{the same identifier as the product has}.
Also, developer must use the same identifier when they define their product with Eclipse.

For now we have one product line, one product in it and some exceptional feature to be licensed separately. That's quite enough to proceed to the next part - \textbf{evolution}.

\subsection*{Evolution}
\addcontentsline{toc}{subsection}{Evolution}

Now you defined the features product has, and developers can finally start working around it. When the first version is about to release, it's time to define
a new product and feature versions.

\paragraph*{Define Feature Version}
\paragraph*{}

Let's define our first feature version. Press \textit{Show} button near the Feature sets count: you will see the workspace with two features
you defined earlier (if you did, of course).

\begin{center}
    \includegraphics[width=0.75\textwidth]{feature_set_show}
\end{center}

Then right-click on any feature (we will use previously mentioned stats feature), and then select Feature Version in the context menu.

\begin{center}
    \includegraphics[width=0.75\textwidth]{feature_version_create}
\end{center}

The only thing you have to define here is feature version itself. In ArSysOp we usually prefer \href{https://semver.org/}{semantic versioning} to choose correct version names,
so in this tutorial we will follow these simple rules (you can have a look at them at the provided website).

\begin{center}
    \includegraphics[width=0.75\textwidth]{feature_version_created}
\end{center}

After all you will see something like this.

\textit{Not really obvious, but important remark here is the idea, that in Passage every product \textbf{is} a set of features. In fact you can't license a product,
    but you can license a feature, that represents the product at all or the feature "to launch product" - up to you.} So, let's create an .operator feature version as well.

Now we can go on to the product version definition. Product version contains a set of feature versions: a single release - a single set of feature versions in it.

\paragraph*{Define Product Version}
\paragraph*{}

Open the products workbench with \textit{Show} button near the product lines count.

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_line_show}
\end{center}

To create new product version, right-click in the workbench on the product you want to distribute.

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_version_create}
\end{center}

\paragraph*{Generate keypair}
\paragraph*{}

When you have created product version, after selecting it (just left-click on it) you will see \textit{Keys} button activated. 

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_version_keys}
\end{center}

Press it to generate a keypair to encode and decode license files.
Passage uses asymmetric encoding to deal with license data (this is required to protect licenses from being stolen or falsified). Public and private keys are now located in passage workspace subfolder representing your product
(usually passage workspace is located under your user home folder), you have to share the public one with your developer to include it into the product. The private one remains with you to issue
licenses for your product.

If you see private and public key fields colored in white (instead of red they were), you've done all right.

\paragraph*{Include Features}
\paragraph*{}

Now let's fill our product version with feature versions (as we mentioned above, the product is a set of features).

First, create new product version feature under your product version: this node binds feature version to product version.

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_feature_create}
\end{center}

When the version is created, select the feature you want to include, then type in the version you created earlier and select the restriction level.

\begin{center}
    \includegraphics[width=0.75\textwidth]{product_feature_created}
\end{center}

\paragraph*{Restriction Levels}

\subparagraph*{Info}
This restriction level means that unauthorized usage of your feature is not really bad for your business logic. If user won't have a license for the feature with this restriction
level, they won't even be notified. No restriction in fact.

\subparagraph*{Warn}
This one means that user will be able to use feature if he has no appropriate license, but also they will be notified that it's better to obtain a license for this feature.

\subparagraph*{Error}
Selecting this level restricts any unauthorized usage of the feature. If the user tries to use it with no license, the framework will interrupt him and offer to obtain a license in any way.

\subparagraph*{Fatal}
It is generally used for product definition features to hardly restrict even a launch of the product with no license.

\paragraph*{Add remaining features}
\paragraph*{}

After all, add all your features you want to include in your product version and then you are ready to start issuing licenses.

\subsection*{Licensing}
\addcontentsline{toc}{subsection}{Licensing}

First of all, we have to tell Passage who is this lucky man about to obtain a license for your product. Inside Passage this lucky man is called \textit{User}. 
Every user should have its \textit{User Origin}. This user origin usually represents a company or any other group of users you want to work with.

\paragraph*{Create user origin}
\paragraph*{}

In the Users area press \textit{Create} and create your first user origin. It can be your client company or any other user origin you wish.
User Origin identifier and \textbf{description} here are mandatory.

\begin{center}
    \includegraphics[width=0.75\textwidth]{user_origin_create}
\end{center}

\paragraph*{Create user group}
\paragraph*{}

In any company there are several groups of users with different features access. User Group represents a group of users of the same user origin.
For Cordon Product sounds really well to create Licensers user group representing workers, who issue licenses for Volvo clients. 
Let's create it with the context menu on user origin.

\begin{center}
    \includegraphics[width=0.75\textwidth]{user_group_create}
\end{center}

Fill all the required fields including email address. Passage uses it to automatically send licenses to licensees.

\begin{center}
    \includegraphics[width=0.75\textwidth]{user_group_created}
\end{center}

We've created a user group, but usually we don't issue a license to group of users (if it is not a floating license, of course), then we have to create at least one user.

\paragraph*{Create user}
\paragraph*{}

Imagine Santa Claus working in Volvo. Let's create a user for him.

\begin{center}
    \includegraphics[width=0.75\textwidth]{user_create}
\end{center}

Fill identifier, name, email like in the previous part and also evaluation type.

\textbf{Evaluation type} is a way how license is being authorized. We simply tell the framework a way to determine that it currently works on a computer of its user, not anyone else.
For now there is only one option - hardware. It means that the framework will get the parameters of your system 
(actually, the framework have already got, you can check them with \textit{Inspect hardware} button under \textit{Help} button in top toolbar) and then compare it using the 
\textbf{evaluation expression}, where the rule which hardware the framework should accept is located. Every rule simply looks like:

\verb|hardware.PARAMETER = value (or * if any is appliable)|

For now let's create a rule that checks user OS and applies any of them.

\verb|hardware.os = *|

\begin{center}
    \includegraphics[width=0.75\textwidth]{user_created}
\end{center}

Now add our new user to user group and we are ready to create License Plan for our user.

\paragraph*{Create license plan}
\paragraph*{}

First lets create a license plan - a set of licenses for your product line. Use \textit{Create} button.

\begin{center}
    \includegraphics[width=0.75\textwidth]{license_create}
\end{center}

Then with \textit{Show} button go to License Plans workbench and create new License Plan feature:

\begin{center}
    \includegraphics[width=0.75\textwidth]{license_plan_create}
\end{center}

Select a feature, feature version and a versions compatibility rule.

\paragraph*{Compatibility Rules}

\subparagraph*{Compatible}
This rule accepts all the previous major versions and all minor versions before next major version. The example is always provided under the field.
\subparagraph*{Equivalent}
Accepts all the previous versions and all patches for current minor version.
\subparagraph*{Greater or Equal}
In fact accepts every version.
\subparagraph*{Perfect}
Accepts only the version you selected.

\paragraph*{Issue a license}
\paragraph*{}

Now we are ready to issue a first license. Press the large \textit{Issue a personal license} button in the left part of the window.

Fill the fields in the dialog with the entities we defined earlier. Select validity dates (\textit{In a free version of Passage three months is the maximum validity period.
 If you have no enterprise license, Passage will automatically reduce the license validity period to three months, if it exceeds the limit.})

\begin{center}
    \includegraphics[width=0.75\textwidth]{issue_first}
\end{center}

Check if all the things are right and press \textit{Finish}.

\begin{center}
    \includegraphics[width=0.75\textwidth]{issue_second}
\end{center}

That's it! We've issued a license. Passage tells you where the license files for your user are located and the only thing you need to do here is sending .licen file to your end user.

\begin{center}
    \includegraphics[width=0.75\textwidth]{issue_completed}
\end{center}


\chapter*{Glossary}
\addcontentsline{toc}{chapter}{Glossary}
\markboth{Glossary}{}

\paragraph*{Feature}

The 'Feature' corresponds to the scenario for your product, that you want to restrict. For example, you may want to restrict export to some proprietary format or other actions. You do not need to describe all the functionality of your 'Product', but only the parts you want to restrict. The 'identifier' attribute of the 'Feature' is important for the licensing configuration.

\paragraph*{Feature Set}

The 'Feature Set' groups the related functionality that may be distributed via several 'Products'

\paragraph*{Feature Version}

The 'Feature Version' is a state of your 'Feature' that included to the 'Product Version'.The 'version' attribute of the 'Feature Version' is important for the licensing configuration.

\paragraph*{User}

The 'User' describes the licensee of your functionality. The 'identifier' of the 'User' is a part of the 'License Pack' definition.

\paragraph*{User Origin}

The 'User Origin' provides access to 'User' descriptors. The typical example of the 'User Origin' is the list of users registered on your web site to download 'Product Version'.

\paragraph*{Product}

The 'Product' corresponds to the ready-to-use item in your offering. The 'identifier' attribute of the 'Product' is important for the licensing configuration. 

\paragraph*{Product Feature}

The 'Product Version Feature' describes the state of functionality included to the 'Product Version'. It is used as a reference to formulate 'License Pack'. 

\paragraph*{Product Line}

The 'Product Line' groups the related 'Products' in your offering. It may be different editions of the related functionality.

\paragraph*{Product Version}

The 'Product Version' corresponds to the binaries you are planning to release or already released for the 'Product'. It is recommended to create the 'Product Version' for each external 'Product' shipment. The 'version' attribute of the 'Product Version' is important for the licensing configuration. The 'Product Version' completes the definition of licensing configuration that will be checked in the user environment. 

\end{document}