Getting started

This page mainly serves as an overview and introduction to the different developer courses, but it can also be integrated into your course agenda if needed.

Technical overview

Please read about the Bizzkit technical overview here.

Creating a test environment in Docker

All Bizzkit applications can be run in docker which makes it easy to set up a local environment for test, demo, and development. Please refer to this article for more information.

AUTH and IAM

User Management enables effective management of users and access. Please read the concept article for more information.

Blueprint

All new solutions could be based on Bizzkit Blueprint. Read more about that here.

Cache

Please note that apart from Ecommerce Search's Search Host API, all Bizzkit applications are not designed to be an endpoint. In an e-commerce solution, you need to implement cache functionality.

Bizzkit versions

Please read about the Bizzkit Release cycle here.

SDK

All applications have a standard (Swagger/OpenAPI) REST API where you can test the different methods and view all request and response models. Read about the SDK and see some example code here.

Getting started

To make it as simple as possible to try the SDK in .NET follow these steps:

Make sure the installation you are using have a machine downstream client with a clientId/clientSecret and needed scopes. In the this example the following are expected
- ClientId: BizzkitClient
- ClientSecret: BizzkitSecret
- Scopes: iam/, damapi/, cmsapi/, pimapi/, searchapi/, courierapi/, mailapi/
Create an empty folder and create a bash/shell/terminal here
Create a C# .NET 8 Console application

dotnet new console -n MyApp

Navigate to /MyApp and add a nuget.config providing reference to the Bizzkit packages

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="bizzkit-partner" value="https://pkgs.dev.azure.com/bizzkit-platform/7dad82b4-f2ae-4a3a-ab87-3fc791e4ea62/_packaging/bizzkit-partner-feed/nuget/v3/index.json" />
    <add key="nuget-source" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

Add packages

dotnet add package bizzkit.sdk.iam
dotnet add package bizzkit.sdk.dam
dotnet add package bizzkit.sdk.pim
dotnet add package bizzkit.sdk.search
dotnet add package bizzkit.sdk.ecommercesearch
dotnet add package Bizzkit.Sdk.Search.Authenticated
dotnet add package bizzkit.sdk.cloudmail
dotnet add package Microsoft.Extensions.Logging.Console
dotnet add package Microsoft.Extensions.DependencyInjection

Replace Program.cs with this (and change URLs in DomainConfig if needed - this is going to localhost):

using Microsoft.Extensions.DependencyInjection;
using Bizzkit.Sdk.Iam;
using Bizzkit.Sdk.Dam;
using Bizzkit.Sdk.Pim;
using Bizzkit.Sdk.CloudMail;
using Bizzkit.Sdk.EcommerceSearch;
using Bizzkit.Sdk.Search;
using Bizzkit.Sdk.Search.Authenticated;
using Bizzkit.Sdk.Search.Authenticated.Services;
using ConsolePlayground;


var config = DomainConfig.GetConfigForLocalhost();
var services = new ServiceCollection();
services.AddLogging();
services.AddSingleton<IIamClientFactory>(new IamClientFactory(config.GetIamConnectionOptions()));
services.AddSingleton<IDamClientFactory>(new DamClientFactory(config.GetDamConnectionOptions()));
services.AddSingleton<IPimClientFactory>(new PimClientFactory(config.GetPimConnectionOptions()));
services.AddSingleton<IMailClientFactory>(new MailClientFactory(config.GetMailConnectionOptions()));
services.AddSingleton<ISearchAdministrationClientFactory>(new SearchAdministrationClientFactory(config.GetSearchAdminConnectionOptions()));

HttpClient httpClient = new();
services.AddSingleton<ISearchClientFactory>(new SearchClientFactory(config.GetSearchClientConnectionOptions(), httpClient));
services.AddBizzkitAuthenticatedSearch();

services.AddSingleton<BizzkitTest>();
var provider = services.BuildServiceProvider();

var test = provider.GetService<BizzkitTest>();
if (test != null)
{
    Console.WriteLine(await test.IamTest());
    Console.WriteLine(await test.DamTest());
    Console.WriteLine(await test.PimTest());
    Console.WriteLine(await test.MailTest());
    Console.WriteLine(await test.EcsAdminTest());
    Console.WriteLine(await test.EcsHostTest());

    bool getAuthSearchToken = false;
    if (getAuthSearchToken)
    {
        const string segmentId = "merch-b2c-en";
        const string issuerUrl = "https://www.example.com";
        string[] allowedScopes = ["vip"];   // example
        var filters = new Dictionary<string, Bizzkit.Sdk.Search.FilterModel>
        {
            {
                "PriceGroup",
                new Bizzkit.Sdk.Search.FilterModel
                {
                    Values = new List<string> { "vip" } // example
                }
            }
        };
        await test.CreateSigningKey(config.EcsAdminApiUrl, segmentId, issuerUrl);
        var token = await test.GetAuthenticatedSearchToken(segmentId, allowedScopes, filters, TimeSpan.FromHours(1));
        Console.WriteLine("SearchToken:\r\n" + token.Token);
    }
}


namespace ConsolePlayground
{
    public class BizzkitTest(
        IIamClientFactory iamClientFactory,
        IDamClientFactory damClientFactory,
        IPimClientFactory pimClientFactory,
        IMailClientFactory mailClientFactory,
        ISearchAdministrationClientFactory searchAdministrationClientFactory,
        ISearchClientFactory searchClientFactory,
        IAuthenticatedSearchSigningService authenticatedSearchSigningService
        )
    {
        public async Task<string> IamTest()
        {
            var client = await iamClientFactory.CreateAuthenticatedClientAsync();
            try
            {
                var count = (await client.ListRolesAsync()).Count();
                return "IAM OK";
            }
            catch (Exception ex)
            {
                return "IAM Error: " + ex.Message;
            }
        }

        public async Task<string> DamTest()
        {
            var client = await damClientFactory.CreateAuthenticatedClientAsync();
            try
            {
                var ok = await client.Test_EchoAsync("DAM ok");
                return "DAM OK";
            }
            catch (Exception ex)
            {
                return "DAM Error: " + ex.Message;
            }
        }

        public async Task<string> PimTest()
        {
            var client = await pimClientFactory.CreateAuthenticatedClientAsync();
            try
            {
                var ok = await client.Test_GetAsync();
                return "PIM OK";
            }
            catch (Exception ex)
            {
                return "PIM Error: " + ex.Message;
            }
        }

        public async Task<string> MailTest()
        {
            var client = await mailClientFactory.CreateAuthenticatedClientAsync();
            try
            {
                var ok = await client.ListRolesAsync();
                return "MAIL OK";
            }
            catch (Exception ex)
            {
                return "MAIL Error: " + ex.Message;
            }
        }

        public async Task<string> EcsAdminTest()
        {
            var client = await searchAdministrationClientFactory.CreateAuthenticatedClientAsync();
            try
            {
                var ok = await client.GetVersionInformationAsync();
                return "ECS Admin OK";
            }
            catch (Exception ex)
            {
                return "ECS Admin Error: " + ex.Message;
            }
        }

        public async Task<string> EcsHostTest()
        {
            var client = await searchClientFactory.CreateUnauthenticatedClientAsync();
            try
            {
                var ok = await client.GetVersionInformationAsync();
                return "ECS Host OK";
            }
            catch (Exception ex)
            {
                return "ECS Host Error: " + ex.Message;
            }
        }

        public async Task CreateSigningKey(string? audienceUrl, string? segmentId, string? issuerUrl = "https://mywebshop.example.com/")
        {
            var client = await searchAdministrationClientFactory.CreateAuthenticatedClientAsync();
            var signingKeySettings = new SearchSigningKeySettingsModel
            {
                AudienceUrl = new Uri(audienceUrl!),
                IssuerUrl = new Uri(issuerUrl!)
            };
            await client.UpsertSigningKeySettingsAsync(segmentId, signingKeySettings);
        }

        public async Task<AuthenticatedSearchToken> GetAuthenticatedSearchToken(string segmentId, string[] scope, Dictionary<string, Bizzkit.Sdk.Search.FilterModel> filters, TimeSpan tokenTtl)
        {

            var allowedScopeIds = new HashSet<string>(scope);
            var authSearchModel = new AuthenticatedSearchModel(segmentId)
            {
                AllowedScopeIds = allowedScopeIds,
                Filters = filters
            };
            var tokenOpts = new AuthenticatedSearchOptions { TokenTtl = tokenTtl };
            var token = await authenticatedSearchSigningService.CreateTokenAsync(authSearchModel, tokenOpts);
            return token;
        }
    }

    public class DomainConfig
    {
        public string? Authority { get; set; }
        public string? DamApiUrl { get; set; }
        public string? IamApiUrl { get; set; }
        public string? PimApiUrl { get; set; }
        public string? CmsApiUrl { get; set; }
        public string? EcsAdminApiUrl { get; set; }
        public string? EcsHostApiUrl { get; set; }
        public string? ClientId { get; set; }
        public string? ClientSecret { get; set; }
        public string? MailApiUrl { get; set; }

        public IamConnectionOptions GetIamConnectionOptions()
        {
            return new IamConnectionOptions
            {
                Authority = Authority,
                BaseUrl = IamApiUrl,
                ClientId = ClientId,
                ClientSecret = ClientSecret
            };
        }

        public DamConnectionOptions GetDamConnectionOptions()
        {
            return new DamConnectionOptions
            {
                Authority = Authority,
                BaseUrl = DamApiUrl,
                ClientId = ClientId,
                ClientSecret = ClientSecret
            };
        }

        internal PimConnectionOptions GetPimConnectionOptions()
        {
            return new PimConnectionOptions
            {
                Authority = Authority,
                BaseUrl = PimApiUrl,
                ClientId = ClientId,
                ClientSecret = ClientSecret
            };
        }

        internal MailConnectionOptions GetMailConnectionOptions()
        {
            return new MailConnectionOptions
            {
                Authority = Authority,
                BaseUrl = MailApiUrl,
                ClientId = ClientId,
                ClientSecret = ClientSecret
            };
        }

        internal SearchAdministrationConnectionOptions GetSearchAdminConnectionOptions()
        {
            return new SearchAdministrationConnectionOptions
            {
                Authority = Authority,
                BaseUrl = EcsAdminApiUrl,
                ClientId = ClientId,
                ClientSecret = ClientSecret
            };
        }

        internal SearchConnectionOptions GetSearchClientConnectionOptions()
        {
            return new SearchConnectionOptions
            {
                BaseUrl = EcsHostApiUrl
            };
        }

        public static DomainConfig GetConfigForLocalhost()
        {
            return new DomainConfig
            {
                Authority = "https://localhost:8001",
                DamApiUrl = "https://localhost:8012",
                IamApiUrl = "https://localhost:8002",
                PimApiUrl = "https://localhost:8006",
                CmsApiUrl = "https://localhost:8018",
                MailApiUrl = "https://localhost:8030",
                EcsAdminApiUrl = "https://localhost:8020",
                EcsHostApiUrl = "https://localhost:8021",
                ClientId = "BizzkitClient",
                ClientSecret = "BizzkitSecret"
            };
        }

    }
}

Build and run. When using a installation with the full suite it should result in something like

IAM OK
DAM OK
PIM OK
MAIL OK
ECS Admin OK
ECS Host OK

Now you should be ready to play with the SDK.