--- url: /service-registration.md --- # Registration of the *Service* ## Definition of basic metadata Once the *Service* registration form is opened by clicking on **+ Register Service**, it will be possible to enter the basic metadata: * **Name*:*\* *Service name* * **Version*:*\* *Service version* * **URL*:*\* `docker://:/:` as well as: * **Category** * **Tags** both useful for categorizing the *Services* ::: info Note The service name must not start with a digit (0-9). ::: ![service-registration-form](/images/service-registration-form.png) *Service registration form* ### Documenting a *Service* On the right is instead available an editor for entering the documentation of the *Service* in [Markdown](https://www.markdownguide.org/) format. :::: info `markDown` field in the JSON metamodel When defining the *Service* via JSON metamodel (see [Manual Definition of the Metamodel](./manual-service-metamodel-definition.md)), the documentation must be inserted in the `markDown` field as a **JSON object** with the `value` key, not as a plain string: ```json "markDown": { "value": "# Service Title\n\nDescription..." } ``` Newlines must be escaped as `\n`. The text corresponds to the content of the project's `documentation.md` file. :::: ![service-registration-form-with-markdown-documentation-highlighted](/images/service-registration-form-with-markdown-documentation-highlighted.png) *Service registration - Markdown addition* The entered documentation will be accessible to the Data Scientist user of the *Service* through: 1. *Service* detail page *Service detail - Markdown visualization* 2. *Workflow Designer* Clicking on the *Service* of interest and then on **Documentation** ![workflow-designer-mk-documentation-opening-procedure](/images/workflow-designer-mk-documentation-opening-procedure.png) *Workflow Designer - View documentation* ![workflow-designer-mk-documentation-open](/images/workflow-designer-mk-documentation-open.png) *Documentation detail* ## Definition of Service Properties In the [I/O Ports](./io-ports.md) section, we have seen which command-line arguments to define at the core program level. Now, we will show how to communicate to ALIDA the presence of these arguments, so that the platform can valorize them and pass them correctly. In particular, there **must** be a *Service Property* for each base command-line argument of the core program. You will not need to create those for the command-line arguments **specific to the Datasource**. The *Service Properties* can be of four types: * Application * Static * Resource ## *Application* Type To define *I/O Ports* and *Configurable execution parameters*, it is necessary to register *Service Properties* of type *Application*. Those corresponding to the **base arguments** seen in the [I/O Ports](./io-ports.md) section must be registered. ### *Dataset*, *Model* and *Streaming* Type Ports For each of the **base arguments** of these port types, summarized here: a *Service Property* must be created according to the following rules: * **Key:** `argument name (without '--')` (e.g. `--input-dataset` => `input-dataset`) * **Description:** *optional* * **Type:** `Application Property` * **Mandatory:** `ticked` * **Invisible:** `ticked` * **Value Type:** `String` * **Default Value:** *empty* | `ANY` (in the case of `--input-columns`) * **Data Type:** `Input Data` * **Streaming:** `unticked` ::: tip Example for `--input-dataset` ![service-property-registration-for-input-dataset](/images/service-property-registration-for-input-dataset.png) *Service property insertion form* ::: ::: info Note — *Model* type ports For `--input-model` and `--output-model` ports, the Service Property must include the `model` field with the model format: ```json { "key": "output-model", "type": "application", "mandatory": true, "invisible": true, "valueType": "STRING", "defaultValue": null, "model": { "format": "sklearn" } } ``` Allowed values for `format` include `sklearn`, `mlflow`, `huggingface`. **Do not declare the `id` field** in the property: it is automatically injected by ALIDA at runtime. ::: ### Generic I/O Type Port For a *Generic* type port, the *Service Property* is defined as follows: * **Key:** `assets` * **Description:** *optional* * **Type:** `Application Property` * **Mandatory:** `ticked` * **Invisible:** `ticked` * **Value Type:** `JSON` * **Default Value:** ```json { "inputs":[ { "name":"input-data", "path":"/inputs", "type":"dataset", "description":"my description" } ], "outputs":[ { "name":"output-data", "path":"/outputs", "type":"dataset", "description":"my description" } ] } ``` * **Data Type:** `Input Data` * **Streaming:** `unticked` In this way, inside the container of the corresponding *Service*, two empty volumes accessible by the core program within the container will be mounted under `/inputs` and `/outputs`. **Note:** While creating the workflow, the variable entry editor will change depending on the property type, description, and default values entered. Here is an example for two variables: `message` (JSON type) and `period` (string type): *Documentation detail* ### REST API Type Port The relative *Service Property* is as follows: * **Key:** `portsToExpose` * **Description:** *optional* * **Type:** `Application Property` * **Mandatory:** `ticked` * **Invisible:** `unticked` * **Value Type:** `JSON` * **Default Value:** ```json { "ports":[ { "port":"", "name":"default", "http_model":"rest", "url":null } ] } ``` * **Data Type:** `Input Data` * **Streaming:** `unticked` If this property is included, once the *Service* has been saved and loaded into a *Workflow*, it will allow us to expose it on the network and contact it through a URL provided by Alida at runtime: ### Configurable execution parameter For the definition of execution parameters configurable by the user through the *Workflow Designer* UI: * **Key:** `command line argument name` (e.g. `--my-param` => `my-param`) * **Description:** *optional* * **Type:** `Application Property` * **Mandatory:** `ticked` * **Invisible:** `unticked` * **Value Type:** *all possible* * **Default Value:** *optional* * **Data Type:** `Input Data` * **Streaming:** `unticked` ## *Static* Type *Static* type *Service Properties* allow passing values to the *Service* as **environment variables to the container** and therefore to the core program. * **Key:** `environment variable name` * **Description:** *optional* * **Type:** `Static` * **Mandatory:** `ticked` | `unticked` * **Invisible:** `unticked` * **Value Type:** *all possible* * **Default Value:** *optional* * **Data Type:** `Input Data` * **Streaming:** `unticked` ## *Resource* Type *Resource* type *Service Properties* define the runtime resource quotas requested for the *Service* (Kubernetes), and are all optional parameters. If the runtime cannot satisfy the request, the resources actually allocated will be lower. Allowed metrics are: * **CPU:** expressed in millicores (e.g. `100m`, `1000m` = 1 CPU). * **Memory:** expressed in `Mi` or `Gi`. * **GPU:** whole units (`0`, `1`). * **AllowedRange:** allowed range. For both `application` and `static`, when entering the parameters required by the *Service*, it is possible to call and insert global variables available on the platform with the syntax `{{variableName}}`. The available global variables are present in the "Global variables" section, accessible via the hamburger menu button in the top left: ![global-variable](/images/global-variables.png) ## Preset Values For all three configurable properties of the service, it is possible to define preset values, predefined values that can be used when configuring the service within a workflow. If preset values have been configured, during workflow creation the interface will allow users to select only those values defined by the person who registered the service.