Table of contents

1. Getting started
   1. Overview of tenant administration
   2. Administering your tenant
   3. Configuring a platform service
   4. Using a service API

Getting started

Product teams can get started by accessing an existing tenant or creating a new tenant. Each tenant represents a zone of administrative control and generally products within a common service area can share a tenant.

To create a new tenant

1. Go to ADSP Home;
2. Click the Request a tenant button. (You may require approval from the platform team to complete the tenant creation process.)
3. Congratulations! You have a tenant in ADSP.

Overview of tenant administration

The tenant administration app allows you to configure platform services for your tenant. It consists of three general sections:

1. Navigation menu allows you to switch between items.
2. Main content shows the informational and configuration content of the selected item.
3. Aside that provides links to supporting materials.

Administering your tenant

After your tenant is created, you will have access to the tenant administration application. As the original creator of a tenant, you can login from the landing page of ADSP to access tenant administration.

For other team members, note the instructions and tenant specific login LRN shown in the aside on the Dashboard view (either on the right or the bottom). Team members can login via this url to provision their user in the tenant realm; they will start with no access to tenant administration.

To grant administration access to team members

1. Select Services -> Access in the navigation menu.
2. Use the Keycloak admin portal link to access Keycloak realm administration for your tenant.
3. Select Manage -> Users and click the View all users button.
4. Select the team member you wish to grant access to, and select Role Mappings.
5. Under Client Roles, select urn:ads:platform:tenant-service and add the tenant-admin role.
6. Your team member can now access tenant administration via the tenant specific login url.

Configuring a platform service

You can access configuration for the platform services from the left-side navigation menu in tenant administration. Let’s walk through a simple configuration for the event-service as an example.

To add an event definition

1. Select Services -> Events in the navigation menu.
2. Select the Definitions tab in this view and you will see a list of system defined events.
3. Click Add definition to initiate creation of a new event definition.
4. In the create dialog, enter the namespace and name of your event, then click Save
5. Your new event definition will be shown under its namespace; use the edit icon to modify it.

Using a service API

Once you have an event definition configured, you can use the event service API to send events of this definition.

To create a service account

1. In Keycloak realm administration, from Clients, click Create to create a client to use with a service account.
2. Set Access Type to confidential, Service Accounts Enabled to true, Valid Redirect URLs to https://api.adsp.alberta.ca and Web Origins to +.
3. Select Service Account Roles tab, and under Client Roles, select urn:ads:platform:event-service and add the event-sender role.
4. Select Credentials tab, and take note of the Secret.

To send an event manually

1. In tenant administration, from the Services -> Events view, click the Read the API docs link in the aside (either on the right or the bottom).
2. In API documentation, click Authorize, and login using client_credentials grant with the client created above.
3. Expand the POST /event​/v1​/events endpoint, click Try it out.
4. In the Request body text field, set the namespace and name of the event to match your definition and the timestamp to an ISO2601 timestamp (e.g. 2021-10-02T12:00:00Z).
5. Click Execute to send the request.

To send an event from your application

1. Get an access token with the event-sender role.

   const { access_token } = await fetch(`${keycloakRealmTokenUrl}`, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/x-www-form-urlencoded',
     },
     body: new URLSearchParams({
       client_id: clientId,
       client_secret: clientSecret,
       grant_type: 'client_credentials',
     }),
   });
   

2. Send the event via the event service.

   await fetch(`${eventServiceUrl}`, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${access_token}`,
     },
     body: JSON.stringify({
       namespace,
       name,
       timestamp: new Date(),
       payload,
     }),
   });
   

This is how you can send an event in ADSP. Other services are configured and accessed via API in similar ways.