Uniphar.Sap.OData.Client 7.0.0

sap-odata-client

NuGet package repository for Sap OData Client connection

Purpose

This library is for making calls to SAP (running in AZ). Calls to SAP require a base url. Full path will be decorated with the namespace of the service we call.

Calls to the SAP instance requires authentication with Basic auth - (username and password). These are stored in a secret storage and you do not need to define these. The secret storage can be AZ Keyvault, AWS Secrets Manager or others. Any token expiry is automatically handled by the SAP client and is not something to be concerned with either.

Custom Events

The library also publishes some custom telemetry events. This is because there has been several issues with the SAP Rise environments. We publish the following events

Setup your project to use SapClient package

When using this NuGet package you need to setup a few things in your project

SapClientOptions

The secrets name follow the patter SapClientOptions--{sapApp}--{UserName|Password}:

SapClientOptions--EWM--UserName
SapClientOptions--EWM--Password
SapClientOptions--S4--UserName
SapClientOptions--S4--Password

NOTE: : FetchTokenStatusCodeTriggers is a list of HttpCodes we test against to trigger fetching a new token. We predefine the status code to check for as Forbidden (403). If the issue we encountered before (returning 401 instead of 403) starts again, you need to update the appsettings.json to handle both status codes. You should do that in the project that consumes this NuGet package.

Significant changes with version 2.0.2 UseHttpClientHandler and PooledConnectionLifetime have been retired with version 2.0.2, as we now use short-living http client instances created by HttpClientFactory. These are no longer part of SapClientOptions either.

Program.cs

Add the following to Program.cs

1. Use SapClientKeyVaultSecretManager to map specific credentials to the base configuration

   builder.Configuration.AddAzureKeyVault(
     new Uri(kvUri), tokenCredential,
     new AzureKeyVaultConfigurationOptions
     {
       ReloadInterval = TimeSpan.FromMinutes(30),
       Manager = new SapClientKeyVaultSecretManager("S4") // or "EWM"
     });
   

2. Bind SapClientOptions so it can used in Options pattern:

   builder.Services.Configure<SapClientOptions>(
       builder.Configuration.GetSection(nameof(SapClientOptions)));
   

3. Register a singleton instance of HttpClient, as SapClient makes calls to SAP over HTTP:

   //  If we need to use NullProxy
   if (bool.Parse(builder.Configuration["InstanceConfig:EnableNullProxy"]!))
   {
       builder.Services.AddTransient<ISapClient, NullSapClient>();
   }
   else
   {
       builder.Services.AddTransient<ISapClient, SapClient>();
       builder.Services.AddHttpClient(nameof(SapClient), client =>
       {
           client.BaseAddress = new Uri(builder.Configuration["SapClientOptions:BaseUrl"]!);
           client.Timeout = TimeSpan.Parse(builder.Configuration["SapClientOptions:Timeout"]!);
       });
   }
   

   NOTE: : In the example above we have registered a named client as we intend to use same configuration for all delegated clients when making request to SAP.

Using SapClient library

We have a couple of predefined (and custom) JsonSerialisers we need to use when calling SAP. This is handled by class SapJsonSerializer. It exposes a static method:

  public static JsonSerializerOptions GetJsonSerializerOptions()
  {      
      //  preliminary code logic        
      jsonSerializerOptions.Converters.Add(new SapDateTimeConverter());
      jsonSerializerOptions.Converters.Add(new SapDateTimeOffsetConverter());
      jsonSerializerOptions.Converters.Add(new SapDecimalConverter());

      return jsonSerializerOptions;
  }

The SAP client package exposes two methods

Task<ContentResult> GetAsync<T>(string path, CancellationToken cancellationToken)
Task<ContentResult> PostAsync<T>(string path, T message, CancellationToken cancellationToken)

Both methods return a ContentResult, which means we can handle based on the Http status code in the response.

Example usage:

        public async Task<ActionResult<SalesOrderResponse>> CreateToDoList([FromBody] CreateToDoList createToDoList, CancellationToken cancellationToken)
        {
            //  Call SAP Client to get Serializer Options  
            var serializerOptions = SapJsonSerializer.GetJsonSerializerOptions();
            
            //  Make call to SAP Client  POST method
            var createdTodoListContentResult = await _sapClient.PostAsync("TO_DO_LIST_API", createToDoList.MapToSapToDoListRequest(), cancellationToken);

            switch(createdTodoListContentResult.StatusCode)
            {
                case 201:
                    var createdSapTodoListResult = JsonSerializer.Deserialize<OData<ToDoList>>(createdTodoListContentResult.Content!, serializerOptions);

                    //  Make call to SAP Client GET method                        
                    var sapToDoListWithItems = await _sapClient.GetAsync<OData<ToDoList>>(
                        $"TO_DO_LIST_API/TO_DO_LIST_ITEM('{createdSapTodoListResult!.Data!.Id}')?$expand=to_Item", cancellationToken);
                    
                    var sapToDoList = JsonSerializer.Deserialize<OData<ToDoList>>(sapToDoListWithItems.Content!, serializerOptions);
                    var newSapToDoList = sapToDoList!.Data!.MapToSapToDoListResponse();

                    return CreatedAtAction(nameof(CreateToDoList), new { id = newSalesOrder.Id }, newSalesOrder);
                    
                case 400:
                    var sapErrorResponse = JsonSerializer.Deserialize<SapErrorResponse>(createdTodoListContentResult.Content!, options);
                    return BadRequest(sapErrorResponse!.MapToProblemDetails());
                default:
                    return new StatusCodeResult((int)createdTodoListContentResult.StatusCode!);
            }
        }

OData Batch Query

The Sap Client supports the ability to execute simple batch queries against a SAP OData endpoint.

To execute a batch query against an OData endpoint the ExecuteBatchQueryAsync method can be used to submit and retrieve the result of the batch query.

BatchQueryResponse batchQueryResponse = await sapClient.ExecuteBatchQueryAsync(
    "API_PRODUCT_SRV/$batch?sap-client=200",
    new List<BatchQueryRequest>
    {
        new BatchQueryRequest("A_Product(Product='131187')"),
        new BatchQueryRequest("A_Product(Product='386110')")
    });