fixes for #2

eclipse.preferences.version=1

encoding//src/main/java=UTF-8

encoding//src/main/resources=UTF-8

encoding//src/test/java=UTF-8

encoding/<project>=UTF-8

This service is an **OSL controller** which acts as a **CAPIF 3GPP API Invoker Management layer**. In a nutshell it:

- Registers and manages multiple CAPIF invokers, each one registered as a Resource Specification in the OSL Resource Specification catalog under the category invoker.capif.osl.etsi.org.

- Comminicates with a CAPIF Core component (e.g. https://capifcore.org:443)

- Registers and manages multiple CAPIF invokers each one registered as Resource Specification in OSL Resource Specification catalog under category invoker.capif.osl.etsi.org.

- Talks to a CAPIF Core component (e.g. https://capifcore.org:443)

- Uses ActiveMQ for internal messaging (e.g., TMF catalog operations, orchestration invocations, etc)

- Can automatically onboard Invokers, and manage certificates (via public/private keys)

-   This allows external configuration of multiple API Invokers.

Currently application.yaml onboards two example invokers with self-signed certificates. In general the `capif:` section in `application.yaml` configures the Spring Boot application  to:

Currently application.yaml onboards two example invokers with self-signed certificates. In general the 

    capif:

 section in `application.yaml` configures the Spring Boot application  to:

- Register as an API Invoker with a CAPIF Core

- Use secure credentials (optional keys)

- Periodically refresh tokens

- Discover available APIs

- Define which invokers to onboard

> The configurable `application.yaml` properties are also exposed through the [respective HELM Chart](https://labs.etsi.org/rep/osl/code/addons/org.etsi.osl.controllers.capif.invoker/-/tree/main/helm?ref_type=heads).

----------

## 📤 **Using the OSL CAPIF invoker service**

You may deploy the OSL CAPIF service:

- Locally (intended for development): Following the above example configuration

- via HELM (intended for deployment): Downloading the [HELM chart](https://labs.etsi.org/rep/osl/code/addons/org.etsi.osl.controllers.capif.invoker/-/tree/main/helm?ref_type=heads), editing the `values.yaml` in a similar manner, and installing the chart

From the above example configuration, we will get registered in our OSL Resource Specification catalog two invokers: exampleInvoker and exampleInvoker2.

Regardless the intention, the deployment will register two invokers, i.e., exampleInvoker and exampleInvoker2, as OSL Resource Specifications.

You may utilize them as Resource Specification(s) assigned in a Resource Facing Service to design and order CAPIF-enabled services. 

Use them as Resource Specification(s) assigned in a Resource Facing Service. 

### 📦 **Resource Specification Characteristics**

| `status.discoveredServiceAPIs` | CAPIF API discovery result (JSON) | APIs discovered from CAPIF Core |

| `status.state` | Invoker state enum (e.g., CONFIGURED) | Current CAPIF onboarding status |

| `status.infoMessage` | String (e.g., error or health status) | Any message for the user/operator |

| `status.Health` | Resource health verdict (`UP`, `DOWN`, `GONE`) | Human-readable echo of the resource's X.731 health — see below |

----------

### 🩺 Resource health

Besides the characteristics above, every update this controller writes back to the TMF API declares

the resource's **health**: the ITU-T X.731 attributes `operationalState` and `administrativeState`.

That pair, and *not* `resourceStatus`, is what OSOM folds into a verdict and what moves the owning

service:

| What happened | `resourceStatus` | Health | Attributes | Effect on the service |

|--|--|--|--|--|

| Invoker onboarded, bearer token in hand | `AVAILABLE` | `UP` | `ENABLE` / `UNLOCKED` | reaches **ACTIVE** |

| Onboarding failed, or no invoker of that name is configured | `ALARM` | `DOWN` | `DISABLE` / `UNLOCKED` | demoted, with the reason in `status.infoMessage` |

| Resource deleted | `UNKNOWN` | `GONE` | `DISABLE` / `SHUTDOWN` | reaches **TERMINATED** |

| Nothing reported | — | `PENDING` | both unset | **nothing moves** |

That last row is the one to remember: a resource that declares neither attribute is read as "this

producer has not reported", which neither promotes nor demotes its service. The order does not fail —

it simply never finishes. `resourceStatus` on its own is inventory and pool bookkeeping, and ends no

wait loop.

`usageState` is reported too (`ACTIVE` while the invoker is usable, `IDLE` otherwise). It is

informational: OSOM displays it but never derives a service state from it.

Details in [docs/20260827_1333_x731-health-on-every-write-path.md](docs/20260827_1333_x731-health-on-every-write-path.md).

----------

-   Value types are all **TEXT**.

The above Resource Specification Characteristics will also be exposed as Service Specification Characteristics when you relate the Invoker Resource Specification with a Service Specification.

The above Resource Specification Characteristics will be also exposed as Service Specification Characteristics.

To properly expose the designed Service Specification, you may need the to relate the created Resource Facing Service Specification with a Customer Facing Service Specification. 

Then you can insert this  Resource Facing Service Specification as a related Service Specification in a Customer Facing Service Specification. 

Following, there is an example rule that will get the latest Bearer and perform an API invocation (POST in this example) to an API provider register in the CAPIF server.

Here is an example rule that will get the latest Bearer and perform an API invocation (POST in this example) to an API provider register in the CAPIF server.

![enter image description here](lcm_rule.jpg)

		<springdoc.security.version>1.7.0</springdoc.security.version>

		<springdoc.openapiui.version>1.7.0</springdoc.openapiui.version>

		<keycloak.version>22.0.1</keycloak.version>

		<org.etsi.osl.model.tmf.version>1.1.0-SNAPSHOT</org.etsi.osl.model.tmf.version>

		<org.etsi.osl.model.tmf.version>1.4.0-SNAPSHOT</org.etsi.osl.model.tmf.version>

	</properties>

			<artifactId>spring-boot-starter-web</artifactId>

		</dependency>

		<dependency>

			<groupId>org.springframework.boot</groupId>

			<artifactId>spring-boot-starter-test</artifactId>

			<scope>test</scope>

		</dependency>

		<dependency>

			<groupId>org.springframework.boot</groupId>

			<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>

import org.etsi.osl.tmf.rcm634.model.ResourceSpecificationCreate;

import org.etsi.osl.tmf.ri639.model.Characteristic;

import org.etsi.osl.tmf.ri639.model.ResourceCreate;

import org.etsi.osl.tmf.ri639.model.ResourceHealth;

import org.etsi.osl.tmf.ri639.model.ResourceStatusType;

import org.etsi.osl.tmf.ri639.model.ResourceUpdate;

import org.slf4j.Logger;

    ci = addResourceSpecificationCharacteristicItemShort("status.infoMessage", healthStatus,  EValueType.TEXT.getValue(), description , "", false);

    rsc.addResourceSpecificationCharacteristicItem(ci);

    //ResourceRepoService reports status.Health on every write path, so the specification has to

    //declare it: a characteristic the spec never declares is not part of its contract, and nothing

    //downstream knows to display it. It is the human-readable echo of the resource's X.731 health

    //verdict -- the verdict OSOM itself reads off operationalState/administrativeState, never off

    //this text.

    ci = addResourceSpecificationCharacteristicItemShort("status.Health", ResourceHealth.PENDING.name(),  EValueType.TEXT.getValue(), description , "", false);

    rsc.addResourceSpecificationCharacteristicItem(ci);

    return rsc;

  }

    return null;

  }

  public CapifInvoker refreshBearer(CapifInvoker cif) {

  /**

   * Renews the CAPIF service bearer token of an already onboarded invoker.

   *

   * <p>Failure is propagated rather than swallowed. This method used to catch everything and hand

   * the caller back the invoker it was given, which made "renewed" and "could not renew" the same

   * return value: the caller then wrote a "Bearer token refreshed" message onto a resource whose

   * token was quietly expiring. The caller needs to be able to tell the two apart to report the

   * resource's health honestly.

   *

   * @param cif the invoker whose token to renew

   * @return the invoker carrying the fresh token

   * @throws Exception if the invoker is not onboarded, or CAPIF refused to issue a token

   */

  public CapifInvoker refreshBearer(CapifInvoker cif) throws Exception {

    CapifInvoker resultInv =  onboardedInvokers.get(cif.getName());

    try {

      logger.info("Previous bearer: " + cif.getBearerAccessToken());

      cif = aCapifService.getServiceBearer( resultInv );

      logger.info("new bearer: " + cif.getBearerAccessToken());

    } catch (Exception e) {

      e.printStackTrace();

    if ( resultInv == null ) {

      throw new IllegalStateException( "CAPIF invoker " + cif.getName()

          + " is not onboarded, its bearer token cannot be refreshed" );

    }

    return cif;

    //The token itself is a credential and is deliberately not logged.

    logger.info("Refreshing bearer token of invoker {}", cif.getName());

    CapifInvoker refreshed = aCapifService.getServiceBearer( resultInv );

    logger.info("Bearer token of invoker {} refreshed", cif.getName());

    return refreshed;

  }