Skip to main content

Configuration

SDK​

Streams​

A Stream is a collection of card templates, curated by the workbench member. Atomic is designed to collate multiple cards into a single stream - that stream can include multiple instances of the same card, as well as multiple instances of different cards. In the end, they are all combined into a stream and presented to customers.

You can have many stream containers in your application, and a single card template can also be associated with more than one stream.

Assigning cards to streams is explained in more detail in the Streams and containers guide.

Stream containers​

A Container is embedded in one or more of your apps, rendering a single stream of cards. Containers provide a way for the Atomic SDKs to fetch a particular stream of cards for display. To create a container:

Create a Stream container​

  1. From the Configuration section in the workbench sidebar menu, choose 'Stream containers' in the 'SDK' section. Alternatively, open the command palette and type Stream containers. Then click 'New container'.
  2. Create a name for your container e.g. Homepage Container.
  3. Select the card limit for the container. This defaults to 50.
  4. Select the Stream to present in the container.
  5. Select the theme to style the container.
  6. (optional) Select the dark mode theme to style the container.
  7. Take note of the container ID, you'll need this during SDK installation.
  8. Finally, click on the menu icon at the end of the row displaying your container, and select 'Manage client keys' then select the Client key you configured earlier.

Notifications​

Add and manage notification platforms here, so your customers can receive native mobile notifications on iOS and Android.

Add push notification credentials​

You must have access to the Notification Platform resource to be able to add notification credentials. See more in Workbench members

  1. Open the Atomic Workbench, navigate to 'Configuration' and under SDK select 'Notifications'. Alternatively, open the command palette, type Notifications and select Configuration > Notifications.
  2. Click 'New platform', and select either iOS or Android.
  3. Enter the required information to register the corresponding platform:

  • For iOS,

    • You have two configuration options: iOS and iOS Sandbox. The iOS Sandbox configuration is for development purposes and is applicable only to apps installed via Xcode build. For apps distributed via TestFlight or the App Store, the iOS configuration is required.
    • For iOS Sandbox, you can use either the Apple Sandbox Push Service Certificate or the Apple Push Services Certificate. However, for the iOS configuration, only the Apple Push Services Certificate is suitable.
    • Certificate Authentication: you'll require your app's bundle ID, a P12 export of your push notification certificate and private key, and the password for the P12 export if applicable.
    • Token Authentication: you'll require your apps bundle ID, a p8 export of your signing key, a signing key id and a team identifier.

  • For Android, you'll require your app's ID and your Service account private key (JSON) for push notifications.

You will also need to configure your host app for push notifications. For more information, see the relevant SDK documentation.

Container themes​

Add customizable style across streams, cards, and card elements.

Add a Container theme​

  1. From the Configuration section in the workbench sidebar menu, choose Container themes. Alternatively, open the command palette and type Container themes .
  2. Click the SDK tab
  3. Click Add theme button.

API host​

Where you can configure your SDK integration to interact with Atomic.

API keys​

When you install Atomic's SDKs, you'll need to setup a way of generating signed authentication tokens (JWTs) to Atomic. Atomic needs to verify these tokens, using a public key you save into the Workbench.

Before continuing the below steps to add an API key, make sure you have completed Steps 1 & 2 of Getting Started in the Authentication section.

Add an API Key​

  1. From the Configuration section in the workbench sidebar menu, choose API Keys. Alternatively, open the command palette and type API Keys.
  2. Click New Key.
  3. Add the name, max expiration days, type, JWKS config, then select 'Add'.

API​

Base URL endpoint​

The base URL for interacting with your Environment via the Atomic API.

Authentication controls​

Here you can manage your client ID and client secret API Credentials.

  1. From the Configuration section in the workbench sidebar menu, choose Authentication controls. Alternatively, open the command palette and type Authentication controls.
  2. Click New Credential.
  3. Add the role (Workbench, Events, Auth). Which role is needed, depends on the API request you're making. This is explained in API credential roles.
  4. Give it a name that reflects who is making the API request. This could be people (e.g. "QA engineers") or systems you're integrating with (e.g. "Salesforce-staging"). Atomic does not impose any restrictions on the name and you can always edit the name later.
  5. Select 'Add' - you now have access to the client ID and client secret that is required to authenticate your API requests. Note: you will only be shown the client secret once, at the time of creation.

When an API credential is no longer required, you can delete it in this same view. Any API requests using a deleted credential, will fail.

API credentials are available to every workbench member in the environment with the right permissions.

Permission required

Access to this workbench resource is controlled with a specific API Authentication control permission. See the Permissions guide to configure this permission for your workbench members.

Card templates​

Approvals​

Approvals is an optional configuration that requires cards to be approved before they can be published. If Approvals are not configured, then card templates can be published by any workbench member who has admin permissions on the card template resource.

To set up approvals, you need to do the following:

  1. Create an approval group and assign workbench members to it.
  2. Configure the approval process.

Any subsequent publishing of the new draft versions will be subject to the current approval requirements.

Create an approval group​

Creating groups is explained in detail in the Group section of the preferences page.

You first need to create one or more roles that you can then assign to the group of approvers.

1. Add a role​

Card Template Edit

First add a role that gives permission to view card templates.

Click the 'manage' button in the bottom left corner > Workbench members. Alternatively, open the command palette and type Workbench members. Select Roles, then click Create a new role.

Manage options

Name the role, and give it a clear description. For example:

  • Title: Card Approvers
  • Role description: Role access for card approvers to be able to see card templates

Give it access to the Card template resource, with View level of access.

2. Add the role to a group​

Now create a workbench member group for each unique area of your business that needs to approve a card before publishing. For example, legal, data, and product teams.

Click the 'manage' button in the bottom left corner > Workbench members. Alternatively, open the command palette and type Workbench members. Select Groups, then select Create a new group.

Manage options

Name the first group, and give it a clear description. For example:

  • Title: Card Approvers — Legal
  • Group description: A group for members of our legal team who can approve cards

Now give this group access to the Role created in stage one: the 'Card Approvers' role.

Configure approval permission to only some environments using Permissions

Repeat this step for each group of Workbench members who need to approve cards. For example, you may like to add a group called 'Card Approvers — Data' and 'Card Approvers — Product' also.

3. Add workbench members to group(s)​

When inviting new members into the workbench, you’ll now be able to add them to any of the new approver groups.

If you already have workbench members in your environment, you can now add them to the appropriate group.

Click the 'manage' button in the bottom left > Workbench members, and in the Workbench members tab select the member you wish to edit, and then check the box next to the appropriate Group from step 2. See more at Preferences

Manage options

Configure the approval process​

Go to Configuration > Card Templates > Approvals. Alternatively, open the command palette and type Approvals. Toggle Require card approvals on. This setting applies for the whole environment.

Approvals configuration

Next select all of the groups who are required to approve cards, and select ‘Update’.

The approvals configuration screen enables you to specify one or more groups that need to approve the card before it can be published. If you select multiple groups, each of these groups needs to approve the card template. If a workbench member belongs to multiple approval groups, they can select on behalf of which group(s) they are approving.

Approval override​

It is possible to give someone permission to approve card templates without having all necessary approvals in place, so cards can be approved in a time of extreme urgency.

This can be done by giving Admin permissions on the Approval Override permission.

Approval Override

Customer profiles​

Read more about Customers.

Custom fields​

Create custom fields that match your Customer's data. These fields will be available to view, edit, and filter.

Add a Custom field

  1. From the Configuration section in the workbench sidebar menu, choose Custom fields. Alternatively, open the command palette and type Custom fields.
  2. Click New Field
  3. Add the label, name, and type, and select Add.

Tags​

Tags can be used to filter customers and create segments.

Add tags

  1. Go to: Configuration > Customer profiles > Tags. Alternatively, open the command palette and type Tags. Click the New tag button.
  2. Give the tag a name.
  3. Select Save.

Webhooks​

Subscriptions​

View and manage all webhook subscriptions for your application.

Note: individual card webhook subscriptions can also be see managed within each card editor.

Webhook request log​

Beta feature

The Webhook request log is currently in beta.

In the overflow menu of the webhook subscriptions list there is an option to view the subscription's "Request log". Clicking this option will open a new tab showing details of the requests triggered by this webhook subscription. Selecting one of the log entries will populate the screen with information including the target URL and the request and response data. Request and response data is redacted for requests that are not marked as being a test (triggered by the Send test button).

Webhook credentials​

Manage credentials used to authenticate outgoing webhook requests.

There are three credential types which are currently supported, AWS signed request, OAuth client credentials and basic auth.

Add webhook authentication credentials​

  1. Go to: Configuration > Webhooks > Webhook credentials. Alternatively, open the command palette and type webhook credentials.
  2. Select New credential.
  3. Add details for the new credential.
  4. Select Save.

OAuth client credentials​

Oauth credentials are cached within the platform for 45 seconds after initially being retrieved. This is to avoid overloading the Oauth endpoint with requests. Any token expiration settings should be longer than 45 seconds.

The OAuth client credentials flow supports two request schemes:

Request body​

Example of an equivalent request using curl. Credentials are URL encoded and sent in the request body.

curl --location --request POST https://login.microsoftonline.com/common/oauth2/v2.0/token \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_secret=MY_CLIENT-SECRET' \
    --data-urlencode 'client_id=MY_CLIENT_ID' \
    --data-urlencode 'scope=MY_SCOPE'
URL​

Example of an equivalent request using curl. Credentials are encoded using query parameters.

curl -request GET 'http://my.auth.com/oauth2/v2.0/token?grant_type=client_credentials&client_secret=MY_CLIENT-SECRET&client_id=MY_CLIENT_ID&scope=MY_SCOPE'

AWS Signed Request​

Authenticate a request with AWS IAM, this allows webhooks to interact with AWS services. We recommend creating a bot user in AWS with IAM policy access granted only as-required for use with this credential-type.

  • Access key ID: the ID of the access key associated with the AWS IAM user.
  • Secret access key: the secret access key associated with the AWS IAM user.
  • Sign query: optionally sign the request query instead of adding an Authorization header.
  • Session token: optionally provide the session token to use IAM STS temporary credentials.

Basic auth​

Adds an Authorization header containing the provided username and password encoded as per the standard pattern.

This option is less secure, consider using the alternative options where possible.

Analytics export settings​

Configure the data included in analytics exports:

  • Test cards
  • Request payload
  • Card response data

These settings are explained in detail in the Analytics data preferences section of the Analytics guide.

Testing​

Test accounts​

Create and manage test accounts for your SDK integrations.

You may also want to add test accounts in order to test the look and feel of your Cards on your own devices. For more information, see the Testing a card section.

Read more about adding test accounts in the sending cards tutorial.

Last updated on