Skip to main content

Message Provider - Templates

Message provider service source and templates management.

Key endpoints​

Message source

  • [GET] https://[HostName]/api/asol/mp/api/v1/MessageSources
    • Get message sources for message templates

Message templates

  • [GET] https://[HostName]/api/asol/mp/api/v1/MessageTemplates
    • Get message templates

Message Source​

Source represents a part of application (e.g. feature, category) categorizing a message.

  • RESTful API for CRUD actions provided

Message Template​

Template represents a template to render the message subject and body when a new message is sent. Default template is used automatically when message has assigned a specific message-source. Template can be assigned to a message also directly.

Template is organized in two level hiearchy:

  • root level represents implicit plain-text template used for templating of internal message
    • at root level the code and source assignment is required, but channel and format aren't defined
  • the secondary level (optional) is defined for specific channel (e.g. Email) and format (e.g. Html)
    • at 2nd level the channel and format must be specified, but code and source is derived from parent template

Example message template​

  • Example of plain-text template
Hello, ${firstName} ${lastName}!
Click to start: ${url}
  • Example of HTML template
<html>
  <body>
    <p>{:Hello, ${firstName} ${lastName}!:}</p>
    <a href="{:${url}:}">Click to start</a>
  </body>
</html>

Template seeding (Metadata exchange)​

Prerequisites​

Message Provider contains definitions of message sources and message templates. These metadata are static, so message provider expects active (i.e. push) metadata exchange pattern. A new version of application/service can bring an updated message source or template. These metadata should be checked and pushed into message provider, e.g. during service startup.

Important: Currently used metadata can be stored in master or tenant specific database. The preferred way is to use one shared definition across all tenants and stored in master database.

Example: Domain (service) implementation of metadata-importer​

public class MessageProviderMetadataImporter : IMessageProviderMetadataImporter
{
    public Task ImportMetadataAsync(IMessageProviderMetadataConfigurator configurator, MessageAccess access, CancellationToken ct = default)
    {
        //note: use 'access' parameter to determine tenant/master metadata
        switch (access)
        {
            case MessageAccess.Public:
                break;  
            default:
                return Task.CompletedTask;
        }

        var assembly = typeof(MessageProviderMetadataImporter).Assembly;

        //use fluent-api configurator to set-up metadata-exchange
        return configurator
            //to delete a specific message-source (optional)
            .DeleteMessageSource("<code>")
            //to synchronize a specific message-source stored as embedded resource
            .RegisterMessageSource(assembly, "<resource_path>.<resource_name>.json")
                //to delete a specific root template (optional)
                .DeleteRootTemplate("<code>")
                //to synchronize a specific root template stored as embedded resource
                .AddRootTemplate(assembly, "<resource_path>.<resource_name>.json")
                    //to delete a specific child template (optional)
                    .DeleteChildTemplate(<message_channel>, <message_format>)
                    //to synchronize a specific child template stored as embedded resource
                    .AddChildTemplate(assembly, "<resource_path>.<resource_name>.json")
                //to delete other templates in message-source (optional)
                .DeleteOtherTemplates(<predicate_to_delete_other_templates>)
            .SynchronizeAsync(access, ct);
    }
}

Example of message source definition JSON file stored as embedded resource​

{
  "iconId": "https://<frontend path to message source icon>/icon.svg",
  "name": {
    "values": [
      {
        "locale": "en-US",
        "value": "MyExample message source localized name"
      }
    ]
  },
  "code": "MyExample"
}

Registration of metadata-importer into dependency injection​

public static class Startup
{
    //...
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApiConnectorInfrastructure();
        //...
        services.Configure<MessageProviderClientOptions>(Configuration.GetSection(MessageProviderClientOptions.DefaultSectionName));
        services.AddMessageProviderClient();
        //...
        //registration of metadata-importer
        services.AddMessageProviderMetadataImporter<CustomMessageProviderMetadataImporter>();
        //...
    }
    //...

    //...
    public void Configure(IApplicationBuilder app, ...)
    {
        //...
        //import tenant-specific metadata (optional)
        app.UseMessageProviderTenantMetadataImporter();
        //...
    }
    //...
}