Client Library (NuGet package)

To simplify the usage of all public APIs provided by the Deviation Processor, the module offers a client library. This client library acts as a wrapper around the public APIs, providing a more user-friendly interface for interacting with the Deviation Processor. It is released as a NuGet package named Bosch.Nexeed.SMC.DeviationProcessor.Clients.

General Preconditions

To use the Deviation Processor client, it is essential to configure the scope for the named client SmDpPublicClient within the MACMA configuration of your module. This can be done by setting the appropriate environment variable: OIDCNamedHttpClientsClientsSmDpPublicClientScopes__0.

Using the Client Library to Utilize the Public APIs

To integrate the Deviation Processor into your application, you need to register the necessary services in the Dependency Injection (DI) container. This can be accomplished by calling the following method in the ConfigureServices method of your Startup.cs file:

services.AddDeviationProcessorPublicClient("<URL_To_DeviationProcessor>");

Replace <URL_To_DeviationProcessor> with the actual URL of the Deviation Processor on your server. This method will inject a scoped implementation of IDeviationProcessorPublicClient, which you can use for carrying out the actions offered by the public API of the Deviation Processor.

Using the Client Library to Register Actions as a Reactor

For a comprehensive overview of integrating reactor modules, please refer to the Reactor How-To.

Preconditions

Before registering actions, ensure the following configurations are in place:

The necessary configuration as described below.
The ITenantAccessor from Foundation Components is registered in DI: services.AddTenantManagement();.
The DefaultTenantConfig from Foundation Components is registered in DI: services.AddDefaultTenantConfig(IConfiguration);.

Usage option 1

To register one or multiple actions as a reactor at the Deviation Processor, follow these steps:

Call the following method in the ConfigureServices method of your Startup.cs file: services.RegisterActionAtDeviationProcessorUsingHostedService(IConfiguration, List<PostRegisteredAction>);.
- Here, IConfiguration should be the instance containing the settings for the DeviationProcessorClient.
- Here, List<PostRegisteredAction> should be a list of actions to register at the Deviation Processor. It is your responsibility to fill fields such as ModuleMacmaScope, ReactionEndpoint and ValidationSchema accordingly.
- This method will inject a hosted service that attempts to register each action individually every 30 seconds until successful.

Configuration Fields and Examples

Each module has to define for itself how to decide if the registration at the DeviationProcessor should happen or not. The recommended approach is to add an Enabled property to the Configuration under the key DeviationProcessor.

The Configuration for the Client should be structured under the key DeviationProcessor. Below are the expected fields and their descriptions:

Field Name	Description
BaseUrl	The base URL of the Deviation Processor.

Field Name

Description

BaseUrl

The base URL of the Deviation Processor.

Each entry in the list of PostRegisteredAction objects should be structured as follows:

Field Name	Description
Id	A unique identifier for the action. This is the ID of the embedded view context contribution if embedded views are used.
ContributionId	The contribution ID of the embedded view registered in the portal. This is required if the type is EmbeddedView.
Module	The name of the module registering as a reactor, applicable when Action.Type is UiSchema.
Name	The English name of the action, applicable when Action.Type is UiSchema.
Localization	Localization details for the different fields of the action, applicable when Action.Type is UiSchema.
ModuleMacmaScope	The MACMA scope of the module registering as a reactor.
ValidationSchema	The JSON schema for user-defined fields, applicable when Action.Type is EmbeddedView. Refer to the Usage section for additional hints.
ReactionEndpoint	The endpoint where deviations and user-defined fields can be sent.
Type	Specifies whether the action is of type UiSchema or EmbeddedView. Defaults to UiSchema.

Field Name

Description

A unique identifier for the action. This is the ID of the embedded view context contribution if embedded views are used.

ContributionId

The contribution ID of the embedded view registered in the portal. This is required if the type is EmbeddedView.

Module

The name of the module registering as a reactor, applicable when Action.Type is UiSchema.

Name

The English name of the action, applicable when Action.Type is UiSchema.

Localization

Localization details for the different fields of the action, applicable when Action.Type is UiSchema.

ModuleMacmaScope

The MACMA scope of the module registering as a reactor.

ValidationSchema

The JSON schema for user-defined fields, applicable when Action.Type is EmbeddedView. Refer to the Usage section for additional hints.

ReactionEndpoint

The endpoint where deviations and user-defined fields can be sent.

Type

Specifies whether the action is of type UiSchema or EmbeddedView. Defaults to UiSchema.

Example

...
  var serviceUrl = configuration.GetValue<string>("Portal:Info:BaseUrl");
  var oidcClientId = configuration.GetValue<string>("OIDC:ClientId");

  services.RegisterActionAtDeviationProcessorUsingHostedService(configuration, GetActionsToRegister(serviceUrl, oidcClientId));
...

  private static List<PostRegisteredAction> GetActionsToRegister(string serviceUrl, string oidcClientId)
  {
    return
    [
      GetCreateTicketAction(),
    ];

    PostRegisteredAction GetCreateTicketAction()
    {
      var reactionEndpointUri = new Uri(serviceUrl + "/api/v1/{tenantId}/deviation");
      var validationSchema = JsonNode.Parse(File.ReadAllText("<path to validationSchema.json>"))?.AsObject();

      return new PostRegisteredAction
      {
        Id = "bci.ticketmanagement.createticket",
        ContributionId = "991911a9-bdd7-4442-a069-3f54999fdfed",
        Name = "Create Ticket",
        Module = "Ticket Management",
        Localization = new Localization
        {
          Name = new Dictionary<string, string>()
          {
            { "de", "Ticket erstellen" },
            { "fr", "Create ticket" },
          }
        },
        ModuleMacmaScope = oidcClientId,
        ValidationSchema = validationSchema,
        ReactionEndpoint = reactionEndpointUri,
        Type = RegisteredActionType.EmbeddedView
      };
    }
  }

Usage option 2

The option using the Configuration is deprecated and subject to removal soon.

To register an action as a reactor at the Deviation Processor, follow these steps:

Configure your action according to the guidelines in the Configuration Fields section below.
Call the following method in the ConfigureServices method of your Startup.cs file: services.RegisterActionAtDeviationProcessorUsingHostedService(IConfiguration);.
- Here, IConfiguration should be the instance containing your action settings.
- This method will inject a hosted service that attempts to register the action every 30 seconds until successful.
- Additionally, you can provide an optional parameter to specify a file path for the validation schema. While it is possible to include this configuration in your code itself, using the optional parameter is recommended for clarity.

Configuration Fields and Examples

The configuration for the action should be structured under the key DeviationProcessor. Below are the expected fields and their descriptions:

Field Name	Description
Action	The action to register at the Deviation Processor.
Action.Id	A unique identifier for the action. This is the ID of the embedded view context contribution if embedded views are used.
Action.ContributionId	The contribution ID of the embedded view registered in the portal. This is required if the type is EmbeddedView.
Action.Localization	Localization details for the different fields of the action, applicable when Action.Type is UiSchema.
Action.Name	The English name of the action, applicable when Action.Type is UiSchema.
Action.Module	The name of the module registering as a reactor, applicable when Action.Type is UiSchema.
Action.ModuleMacmaScope	The MACMA scope of the module registering as a reactor.
Action.ReactionEndpoint	The endpoint where deviations and user-defined fields can be sent.
Action.UserDefinedFieldsUiSchemaEndpoint	The endpoint to retrieve the JSON schema for user-defined fields, applicable when Action.Type is UiSchema.
Action.ValidationSchema	The JSON schema for user-defined fields, applicable when Action.Type is EmbeddedView. Refer to the Usage section for additional hints.
Action.Type	Specifies whether the action is of type UiSchema or EmbeddedView. Defaults to UiSchema.
BaseUrl	The base URL of the Deviation Processor.

Field Name

Description

Action

The action to register at the Deviation Processor.

Action.Id

A unique identifier for the action. This is the ID of the embedded view context contribution if embedded views are used.

Action.ContributionId

The contribution ID of the embedded view registered in the portal. This is required if the type is EmbeddedView.

Action.Localization

Localization details for the different fields of the action, applicable when Action.Type is UiSchema.

Action.Name

The English name of the action, applicable when Action.Type is UiSchema.

Action.Module

The name of the module registering as a reactor, applicable when Action.Type is UiSchema.

Action.ModuleMacmaScope

The MACMA scope of the module registering as a reactor.

Action.ReactionEndpoint

The endpoint where deviations and user-defined fields can be sent.

Action.UserDefinedFieldsUiSchemaEndpoint

The endpoint to retrieve the JSON schema for user-defined fields, applicable when Action.Type is UiSchema.

Action.ValidationSchema

The JSON schema for user-defined fields, applicable when Action.Type is EmbeddedView. Refer to the Usage section for additional hints.

Action.Type

Specifies whether the action is of type UiSchema or EmbeddedView. Defaults to UiSchema.

BaseUrl

The base URL of the Deviation Processor.

Example: Registered Action Using Embedded Views

{
    "DeviationProcessor": {
        "Action": {
            "Id": "bci.ticketmanagement.createticket",
            "ContributionId": "991911a9-bdd7-4442-a069-3f54999fdfed",
            "Name": "Create Ticket",
            "Module": "Ticket Management",
            "ModuleMacmaScope": "cj81923uhaskldfgi",
            "Localization": {
                "Name": {
                    "de": "Ticket erstellen",
                    "fr": "Create ticket"
                }
            },
            "ReactionEndpoint": "http://somepath/api/v1/{tenantId}/deviation",
            "ValidationSchema": "<schema as string>",
            "Type": "EmbeddedView"
        },
        "BaseUrl": "http://localhost:58009"
    }
}

Example: Registered Action Using UI Schema

The UI-schema approach is deprecated and subject to removal soon.

{
    "DeviationProcessor": {
        "Action": {
            "Id": "bci.ticketmanagement.createticket",
            "Name": "Create Ticket",
            "Module": "Ticket Management",
            "ModuleMacmaScope": "cj81923uhaskldfgi",
            "Localization": {
                "Name": {
                    "de": "Ticket erstellen",
                    "fr": "Create ticket"
                }
            },
            "ReactionEndpoint": "http://somepath/api/v1/{tenantId}/deviation",
            "UserDefinedFieldsUiSchemaEndpoint": "http://somepath/api/v1/{tenantId}/deviation/schema",
            "Type": "UiSchema"
        },
        "BaseUrl": "http://localhost:58009"
    }
}