Question 1

How can I password-protect my hub with Auth0?

Accepted Answer

Malcolm supports using Auth0 to password-protect your content.

This guide will help you set up Auth0.

First go to MyMalcolm > Settings > Instance > Visibility and enable Hosted Hub password protection. This automatically enables the built-in password protection.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/ea8meZWJKM/Screenshot%202021-11-25%20at%2016.37.03.png (Screenshot 2021-11-25 at 16.37.03.png)

Next, inside your Auth0 tennant, create a new Auth0 Application. Give it a name and choose Regular Web Applications from the four options.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/VDfX0QpiZh/Screenshot%202021-11-25%20at%2016.31.49.png (Screenshot 2021-11-25 at 16.31.49.png)

Click on the Settings tab and scroll down to the Basic Information section.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/JReEIPSyji/Screenshot%202021-11-25%20at%2016.46.53.png (Screenshot 2021-11-25 at 16.46.53.png)

In MyMalcolm click through to Manage password protection and toward the bottom enable Auth0 for password protection. Copy/paste the Domain, Client ID and Client Secret from Auth0 into MyMalcolm.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/mwX1ffzhIZ/Screenshot%202021-11-25%20at%2016.40.03.png (Screenshot 2021-11-25 at 16.40.03.png)

Next copy/paste the Application Login URI, Allowed Callback URL and Allowed Logout URL from Malcolm! into your Auth0 Application URIs settings.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/ST4LVVMZ3x/Screenshot%202021-11-25%20at%2016.45.36.png (Screenshot 2021-11-25 at 16.45.36.png)

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/kpvEhZpVtp/Screenshot%202021-11-25%20at%2016.40.39.png (Screenshot 2021-11-25 at 16.40.39.png)

Save the settings on both sides and you should see your Auth0 login page in your Hub.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/oijJOqmb9t/Screenshot%202021-11-25%20at%2016.42.11.png (Screenshot 2021-11-25 at 16.42.11.png)

But that's not all!

Attributes from your Auth0 users can be pre-populated in Malcolm! Workflows. To enable this feature choose a suitable field on a Workflow, edit the field settings and enable Allow a value to be set in the URL query. Enter one of the four attribute names email, name, nickname or picture to pre-populate those values directly into your Workflow.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/5zfBKHJgrE/Screenshot%202021-11-25%20at%2017.23.01.png (Screenshot 2021-11-25 at 17.23.01.png)

You can read more about passing values in the URL query here.

Question 2

Could I use Malcolm! as a publishing platform?

Accepted Answer

Malcolm! has primarily been designed around service interactions with users (eg answering their questions and taking them through a process) but we do have users who use Malcolm! in a more "marketing" or "content" based way eg to host content and/or take their users through forms to download content or register for something.

If you want to use Malcolm! in this way it's worth remembering that you have full branding control (more info here) and can even rename things like FAQ's and Workflows (more info here). You can also change your base URL. See more information in this article.

By default we do mark up FAQs content using https://schema.org/FAQPage so if your content doesn't follow a question and answer format and you allow that content to be indexed by search engines you may wish to change the schema to https://schema.org/WebPage. You can see how to do this here.

The Examples section on our website may give you some further ideas on how you could use Malcolm!

If you want to go even further you might want to consider contacting us and having a chat. We do offer enterprise packages and bespoke development on top of the Malcolm! Platform.

Question 3

Can I enable reCAPTCHA on my Workflows or FAQs?

Accepted Answer

We now support using Google reCAPTCHA on your Workflows and FAQs/Articles.

When enabled, this will offer protection against spam completions of your Workflows and (if you are using them) the submit feedback and send FAQ/Article by email functionality within Malcolm!

You can find out more about Google reCAPTCHA here.

We support:

reCAPTCHA v3
reCAPTCHA v2 - Invisible
reCAPTCHA v2 - Tickbox

You can enable and configure reCAPTCHA for Workflows and/or FAQs independently. So, for example, you could enable reCAPTCHA protection for Workflows but not FAQs. You could also use a different version of reCAPTCHA for Workflows and FAQs.

You can turn reCAPTCHA on via:

Settings --> FAQs --> reCAPTCHA
Settings --> Workflows --> re CAPTCHA

Start by registering your instance with Google which you can do here.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/xynNm0rZqV/screenshot-my.malcolm.app-2023.04.16-22_02_50.png (Setting up reCAPTCHA in MyMalcolm)

Our dialog will show you the information you need to add to Google's interface. You can then paste the credentials you receive back from Google into MyMalcolm.

When enabled, ReCAPTCHA will work across all formats (ie content on your hosted hub, widgets, overlays and embeds).

Question 4

Can I pass secure values into Malcolm! Workflows via the URL?

Accepted Answer

Passing data into a Workflow via the URL is a feature we've had for a while - read more - but what if the data you want to pass is confidential?

Understandably, you wouldn't want to pass that straight in. Luckily Malcolm! understands how important protecting your data is so we've come up with a solution that allows values to travel safe and secure with minimal effort!

A beginners guide to encryption

Suppose you have a value, such as an account number, that you don't want anyone else to read. Encryption provides a way to scramble this value so only you and the people you share the password or secret key with can read it.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/FR8yDloV2d/encryption-diagram.png (encryption-diagram.png)

The sender uses the secret key to scramble the original value and the encrypted value is sent to the receiver. On receipt of the encrypted value the receiver uses the same secret key to unscramble the value back to the original.

And that's encryption in a nutshell!

Step 1: Generate a secret key

The secret key can be any string you like, but Malcolm! recommends using a random string of at least 36 characters. A simple ruby command can quickly generate one for you.

Keep your secret key safe - you'll need it later!

Step 2: Share your secret key with Malcolm!

We do this via the Workflow Builder. Any question field that supports URL query values can now be secured with your secret key - e.g. text fields, hidden fields, number fields, email address fields, etc.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/g6hGpX1dvl/Screenshot%202021-11-10%20at%2013.43.37.png (Screenshot 2021-11-10 at 13.43.37.png)

Here's a simple example which starts with a text field renamed to "Account number".

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/b4uJV41azB/Screenshot%202021-11-10%20at%2013.51.53.png (Screenshot 2021-11-10 at 13.51.53.png)

To enable URL values open up the edit window, scroll to the bottom and turn on "Allow a value to be set in URL query". Malcolm! will automatically generate a query name for you but you can change it to something different if you prefer.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/7OhxX21Mdq/Screenshot%202021-11-10%20at%2013.52.01.png (Screenshot 2021-11-10 at 13.52.01.png)

Next turn on the "Secure the query value" and paste in your secret key.

Hit save and that completes the configuration!

Step 3: Encrypting values

Malcolm! uses OpenSSL and the "aes-128-gcm" cipher to decrypt values.

Passed values need to be encoded and made up of three parts -

The Initialisation Vector used during the encryption
The Authentication Tag resulting from AEAD ciphers
The encrypted string

Initialisation Vectors are generated using the OpenSSL rand function. For our chosen cipher these need to be exactly 12 bytes long. If using PHP you can use the openssl_random_pseudo_bytes function.

Why 12 bytes? This just happens to be the required length for our chosen cipher. In PHP you can verify this by using the openssl_cipher_iv_length function.

This will output -

Next use the OpenSSL enc function to create the encrypted string. Here's an example using the PHP openssl_encrypt function.

This will assign an Authentication Tag to the $tag variable (passed by reference) and an encrypted string to the $ciphertext variable.

Note - in PHP we pass OPENSSL_RAW_DATA to generate binary data.

Complete the process by concatenating $iv, $tag and $cipertext into a single string - Malcolm! needs all three for the decryption process!

As we're passing this value via the URL we need to first encode it. Use a Base 64 encoder followed by a URL encoder to ensure all the characters are sent correctly. In PHP this is the base64_encode function and urlencode functions respectively.

This is the final encoded string!

For simplicity all the steps from above can be put in a single function.

And that's all there is to it ;)

Question 5

Do I need to pay VAT?

Accepted Answer

Value Added Tax (VAT) is the sales tax in the United Kingdom where Malcolm! trades from. The current UK VAT rate is 20%. Our pricing is quoted excluding VAT.

The UK is no longer a member of the European Union (EU) however the VAT rules around UK companies trading with EU based businesses and EU based individuals continue to apply.

Whether VAT is applicable to your purchase of Malcolm! and how we apply it can be summarised as follows:

If you are a UK customer (individual or business): we charge VAT at 20%
If you are an EU Business and supply a valid VAT number (we check it): we will not charge you any VAT
If you are an individual in the EU: we will charge you VAT at your local country VAT - details here (PDF)
If you are a company or an individual not in the UK or in the EU (eg you are in the USA or Australia): we will not charge you any VAT

Question 6

What are promos and how can I use them?

Accepted Answer

Promos are part of your hosted hub theme and are very flexible multi purpose content areas that appear towards the bottom of your hosted hub homepage (and also your FAQs only and Workflows only home if you are using those).

You can use them to link to content within your Malcolm! instance, for example a particular category, tag, FAQ or Workflow and you can also use them to link out to content or functionality you may have elsewhere. They can be a great tactical tool as well, for example if you've a YouTube channel and want to draw attention to it use a promo!

On our own Malcolm! Help & Support Hub the "Upgrade your content" and "Hey there!" areas are promos.

Promos on Malcolm!

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/j0yBsWZi2d/screenshot-support.malcolm.support-2022.08.03-06_58_32.png (Promos on Malcolm!)

Promos on Malcolm!

Promos are created and managed via your theme (Brand --> Themes).

Promo management in MyMalcolm

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/6O1572FsqO/screenshot-my.malcolm.app-2022.08.03-07_03_19.png (Promo management in MyMalcolm)

Promo management in MyMalcolm

When creating a promo you have various options such as uploading your own background image, plus configuring links

Adding a promo in MyMalcolm

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/QnCg1Rjnpm/screenshot-my.malcolm.app-2022.08.03-07_03_59.png (Adding a promo in MyMalcolm)

Adding a promo in MyMalcolm

Also see featured boxes for similar functionality that enables you to create and manage content towards the top of your hosted hub home page.

Question 7

What are Integrations?

Accepted Answer

Integrations are a way of passing data you collect in a Malcolm! Workflow into other third party software or systems.

We currently offer integrations with:

Plus over 1,500 over apps via Zapier (more info here) and Make (formerly Integromat) (more info here).

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/v5lAa3NjkY/zapier-fb%402x.png (Malcolm! Integrations)

Configuring Integrations

Once you have created your Workflow, go to the Configure section and select Integrations. There you can link your third party accounts at our integration partners to your Malcolm! Instance by providing your credentials. Once your accounts are linked you can configure integrations with that partner and choose the data from your Workflow that is passed across. You can configure whether data is passed on every Workflow completion or only when certain conditions are met. It is possible to have multiple integrations so, for example, you could create a form which collected details from a new customer including a copy of their ID. You could then subscribe that new customer to a Mailchimp mailing list and store their uploaded ID documents in your Dropbox account by creating two integrations.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/5KmZGb3Q9Q/screenshot-my.malcolm.app-2019.08.06-19_50_53.png (Integrations in MyMalcolm)

Customer Consent

A reminder that it is good practice - and in certain territories a legal requirement - to ensure that your customers actively consent to their data being passed to third party companies who, like Malcolm!, act as data processors on your behalf. You act as the data controller. Most companies handle this consent via provisions in their Privacy Policy which their customers agree to. It is good practice therefore to include a check box in your Workflows that reminds customers of your Privacy Policy and their continuing agreement of it.

Integration Failures

Sometimes integrations may fail. This could be for a variety of reasons, for example the integration partner's API's may be down and/or there may be a problem with your account at the third party provider (for example your Dropbox account may be over quota).

Firstly don't worry re losing customer data - Malcolm! will always store any user submitted data so if there is a problem with an integration

When a problem occurs we'll create a notification to let you know and periodically retry the integration. You can review the Integration logs and retry a failed integration event manually via MyMalcolm (navigate to the Workflow via Library then select Integration logs).

More Integrations coming soon!

We will be adding more and more integrations to Malcolm! in the coming months. If there is a particular integration you'd like us to add please let us know.

Question 8

Can I have a different logo on FAQ / Workflow pages?

Accepted Answer

Sometimes you might want to use a different logo on your hosted hub homepage to the rest of your hosted hub. If you are using a header image on the hosted hub homepage for example you might want to use a reversed or alternate logo that works well on top of that image.

You can specify a secondary logo inside the header section of your theme.

Question 9

What is the Share section in MyMalcolm for / how does it work?

Accepted Answer

The Share section of MyMalcolm gives you tools to embed and share content from Malcolm! into your existing websites, applications and social spaces.

You can bring content from Malcolm! directly into your current website via embeds. Choose the content you want to embed and how you want it displayed and we'll give you some code. Inserting that code into your current website will load in your content from Malcolm!

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/N17DhjfW2Z/Screenshot%202021-12-30%20at%2013.57.57.png ("Choose your embed type in MyMalcolm)

You can embed individual FAQs or Workflows, create custom widgets that can pull in things like search results, category listings, all content by a particular author, recent content, tagged content, most popular content and much more.

If you don't have a website or you want to group all your Malcolm! content together you can use our Hosted Hub.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/77KnCbIxOb/screenshot-my.malcolm.app-2019.11.05-11_21_58.png (About our Hosted Hub)

We also have a plugin for Wordpress.

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/3xBONmPNuf/screenshot-my.malcolm.app-2019.11.05-11_06_58.png (The Share section of MyMalcolm)

In addition to the above customers on our Enterprise plans have full access to our API which means they can pull from and push content to Malcolm! in a variety of ways - please speak to your account manager for more details.

Question 10

What are invisible tags and how do I use them?

Accepted Answer

Invisible tags are a useful way you can influence search results. Like normal tags they will contribute to search ranking of an FAQ, but they won't be shown on the front-end to your users. If you therefore want a particular phrase to return a particular FAQ but your content doesn't feature that phrase or is being out ranked by another FAQ invisible tags can help.

You can make current tags invisible or set up new invisible tags in MyMalcolm via FAQs / Tags:

https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/xOq4M1EP9q/01%20-%20screenshot-my.malcolm.app-2019.10.16-13_56_00.png (Creating an invisible tag)

You then apply tags as usual via the configure area of the individual FAQ: