Question 1

How do I create a Frequently Asked Question (FAQ)?

Accepted Answer

Within MyMalcolm go the FAQ Section and click "Create a FAQ" towards to the top right of the screen.

This will bring up the "compose your question and answer" dialogue. Here you can input the question, an optional brief summary answer (used in search and browse results) and your full answer. For tips on how to write a good FAQ click here!

When composing your FAQ you can use the formating controls in the "full answer" box or directly enter Markdown. Markdown is a great way of quickly adding formatting to textual content. If you've not used it before it can take a minute or two to get used to it but it's very fast to work with once you have got the hang of it. You can click the "Need help with Markdown?" button bottom left anytime for a quick reference Markdown guide.

You can see what your FAQ will look like to your users by pressing the "Preview" button top right. When you have written your content press "Next: Configure" to move onto the configuration options for your FAQ.

In this area you can control various things about your FAQ such as whether an author is shown, what the URL is, your choice of tags, whether the feedback form is enabled and the category or categories the FAQ lives in. You also have various options around whether the FAQ can be seen by search engines, is password protected or not and can be found or not via the Malcolm! search/browse capability. You can even set the FAQ (or versions of it) to publish and un-publish automatically at certain dates and time in the future.

Watch a video guide to creating an FAQ below.

Question 2

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.

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.

ruby -rsecurerandom -e 'puts SecureRandom.hex(18)'

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.

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

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.

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.

$iv = openssl_random_pseudo_bytes(12);

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.

echo openssl_cipher_iv_length('aes-128-gcm');

This will output -

12

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

$plaintext = 'The text you would like to encrypt'; $cipher = 'aes-128-gcm'; $key = 'xxxxxx'; $iv = openssl_random_pseudo_bytes(12); $ciphertext = openssl_encrypt($plaintext, $cipher, $key, OPENSSL_RAW_DATA, $iv, $tag);

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!

$rawstring = $iv . $tag . $ciphertext;

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.

$encodedstring = urlencode(base64_encode($rawstring));

This is the final encoded string!

$url = '/workflows/encryption-test?account-number=' . $encodedstring;

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

/** * Create a secure a value for a URL query. * * @param string $plaintext * @param string $key * @return string */ function secure_url_value($plaintext, $key) { $iv = openssl_random_pseudo_bytes(12); $ciphertext = openssl_encrypt($plaintext, 'aes-128-gcm', $key, OPENSSL_RAW_DATA, $iv, $tag); $rawtext = $iv . $tag . $ciphertext; $encodedtext = urlencode(base64_encode($rawtext)); return $encodedtext; }

And that's all there is to it ;)

Question 3

What is an Instance?

Accepted Answer

An instance is a collection of related FAQ’s and/or Workflows that your users will see and interact with plus a set of management tools that you and other members of your staff or team will use.

Each instance also includes an optional hosted hub that you can customise and brand.

If you decide to use Malcolm! in two distinct areas of your business it can make sense to have two different instances. For example you could use one instance of Malcolm! to support customers of your product or service and another instance as an internal HR portal.

You can see some examples of how Malcolm! instances can be used here

Instance Billing

Our billing is based around instances. You can start an instance any time and enjoy a 14 day trial. This can be great for trying ideas out. If you want to keep using the instance beyond 14 days you'll need to choose a plan and give us your card details, or agree an enterprise plan with us.

Instance Owners

Each instance will have an owner. This is the master user who is ultimately responsible for the instance. If you are on a Team or Enterprise plan you can invite other users to the instance too. If you need to transfer ownership of the instance to another user (for instance if you are leaving a company or organisation) you can do that as long as the proposed new owner agrees.

Question 4

Can I change the sender and email address in the emails Malcolm! sends my customers?

Accepted Answer

Malcolm! can send emails to your customers/users in the following situations:

Workflow email answers where you have configured the email answer to be sent to the email address specified in the Workflow
Email this answer functionality on an FAQ
Sending the resume later Workflow link
Payment confirmation email

By default these emails come from the sender "Malcolm!" with the email address noreply@malcolm.app You can now change this by connecting Malcolm! to your Mailgun or SendGrid account.

To do this, goto Settings --> Instance --> Emails and toggle Custom email sending to be active. You can then supply your Mailgun or SendGrid credentials and specify your desired sender name and email address.

You can also change the look and feel of these emails - please see this FAQ for further details.

Question 5

How do I use Make (formerly Integromat) to connect Malcolm! to other applications or services I use?

Accepted Answer

Malcolm! now integrates with Make (formerly Integromat). Make is an integration platform - it connects thousands of apps to other apps.

In the context of Malcolm! this means that when a Workflow is completed you can use our Make integration to route some or all of the data that has been collected from that Workflow through into Make and then in turn onto thousands of other apps or services.

Here is how to set things up:

Firstly set up and publish a workflow in Malcolm! that collects the data you wish to move into other applications
In MyMalcolm go to the Settings Section, then Workflows, then Integrations, then click on Make

Sign up for an account at Make if you don't already have one - it is free - or login if you do have an account
In Make click "Create a new scenario"
Search or browse to the third party app/s or service/s you wish to link to your Workflow, select them, then click continue
You will then find yourself in new scenario dialogue of Make. This is where you connect Make to Malcolm! and also your third party apps or services (ie by providing your credentials). Note that Make calls the connection to Malcolm! a webhook.
You then set up the sort of interactions you want to happen when a Malcolm! Workflow is completed. For example you may wish to connect to Google Sheets and have a new row containing the data submitted each time a Workflow is completed. There are also many other powerful options and settings that can be configured from this area. For more detals see Make's guides.

Once you have set things up, you can test the integration by clicking "Run Once" in the Integromat interface, then complete the Malcolm! Workflow in question. The actions you have configured in Integromat should then happen, or you may see details of errors that need correcting.
When you are happy you can then set the scenario to run immediately (ie each time a Workfow is completed) or periodically.
Back in MyMalcolm, if you find the Workflow you set up with Integromat in the Library, select it, then go to Configure then Integrations you should be able to see Integromat has been added. You can turn the integation off here if you want and/or configure it to be conditional (for example to only run when certain choices have been made on a Workflow).

You can also see a video walkthrough below

Remember that Malcolm! always stores your data (which you can download anytime) - so if Integromat goes down or your integration doesn't seem to work properly no data will be lost.

We are hugely excited about the possibilities opened up via Integromat - we hope you are too! If you have questions or need a hand setting things up just contact us and we'll be happy to help.

Question 6

What are Webhooks and how do I use them to receive notifications when Workflows are completed?

Accepted Answer

Webhooks allow you to set up your own integrations to Malcolm! Workflow.

Webhooks are endpoints on web servers you own. Whenever a Workflow is completed the configured Webhooks will be notified. The Payload will contain the completed Workflow Session, related Workflow and (optionally) the submitted Workflow Values.

Configuration

Webhooks are are configured in "Workflows > Edit > Configure > Webhooks" section of MyMalcolm.

Webhook URL

The only requirement is to provide the URL of your Webhook. This is the URL Malcolm! will send the Payload to.

The URL should be a secure endpoint which means it should start with https://, although we do support http:// too. The endpoint should also be accessible which means hosted on a remote machine, not behind a firewall and not requiring Authentication.

Include the Workflow Values

There is an additional option to include the submitted Workflow Values in the Payload. This option is disabled by default for security reasons but available to use should you wish to enable it. By enabling the option you agree to the following terms -

(a) I would like the Workflow Values included in the Webhook Payload (b) the recieving web server is private and properly secured (c) I am aware the use of Webhooks can facilitate the transfer of end-user personal data to third party Data Processors and my use of Webhooks adheres to my responsibilities as Data Controller under applicable Data Protection Laws.

Secure your Webhook with a secret token

Webhook URLs can be called by anyone and are therefore insecure.

To ensure a request to your Webhook URL comes from Malcolm! a secret token known only by yourself and Malcolm! can be used to generate a Signature.

Malcolm! will take the Payload and the secret and create a Signature. This will be passed to your App as the request header X-Signature. Your App will use the same secret and the received Payload to generate a second Signature. If the Signatures match you know the request came from Malcolm! and not another source.

The secret token can be any string you like, but Malcolm! recommends using a random string of at least 36 characters. For example in a Terminal window run -

ruby -rsecurerandom -e 'puts SecureRandom.hex(18)'

To validate the Payload from Malcolm! use the HMAC SHA-256 algorithm to create a hash using the Payload as the data and your secret as the key.

For example in PHP use the hash_hmac function to generate a binary hash.

$key = 'Your secret token'; $data = file_get_contents('php://input'); $hash = hash_hmac('sha256', $data, $key, true); // true = output raw binary data

Next encode the binary hash using a Base 64 encoder, in PHP this is the base64_encode function.

$encoded_hash = base64_encode($hash);

Finally prefix the encoded hash with "sha256=" and compare with the value of X-Signature. In PHP you can use the $_SERVER variable to access the headers.

$signature = 'sha256=' . $encoded_hash; if ($_SERVER['HTTP_X_SIGNATURE'] === $signature) { // Request is valid }

Conditional settings

There are conditional controls available too. If you have a condition configured the Webhook will only be notified if the conditions at the end of the Workflow are satisfied.

Headers

The HTTP POST will contain the following Headers.

Header Description Host The Host of your Webhook URL. Content-Type With value "application/json" X-Instance-Id The ID of the Instance. X-Signature The request Signature, if using a secret token.

Payload

The Payload will be a JSON Body containing the Workflow Session.

Attribute Type Description id string The ID of the Workflow Session. label string A descriptive label, which will include the name of the person who completed the Workflow if your Workflow contains name attributes. description string An extended version of the label which also includes the Workflow name. text string The same as the description but often a attribute named "text" is automatically picked up by some services. locale string The locale used during the Workflow Session. started-at string The date and time the Workflow Session was started, in ISO 8601 format. completed-at string The date and time the Workflow Session was completed, in ISO 8601 format. workflow object[Workflow] The related Workflow. values array[Value] The submitted Workflow Values (if included).

Workflows are defined as -

Attribute Type Description id string The ID of the Workflow. name string The name of the Workflow. published-at string The date and time the Workflow was published, in ISO 8601 format. version string The name of the Workflow version.

Workflow Values are defined as -

Attribute Type Description id string The ID of the Workflow Value. field object[Field] The related Workflow Field. value mixed The submitted value.

Workflow Fields are defined as -

Attribute Type Description id string The ID of the Workflow Field. name string The name of the Workflow Field. query-name string The URL query name for the Workflow Field if defined.

Example

POST /webhook HTTP/1.1 Host: yourdomain.com Content-Type: application/json X-Instance-Id: xxxxxxxxxx X-Signature: xxxxxxxxxx { "id": "xxxxxxxxxx", "label": "Completed by Tom Jordan", "description": "Workflow \"Open Support Ticket\" was completed by Tom Jordan.", "text": "Workflow \"Open Support Ticket\" was completed by Tom Jordan.", "locale": "en-GB", "started-at": "2020-04-01T12:00:00+00:00", "completed-at": "2020-04-01T12:05:00+00:00", "workflow": { "id": "xxxxxxxxxx", "name": "Open Support Ticket", "published-at": "2020-04-01T09:00:00+00:00", "version": "Version 1" }, "values": [ { "id": "xxxxxxxxxx", "field": { "id": "xxxxxxxxxx", "name": "Your name", "query-name": "name" }, "value": "Tom Jordan" }, { "id": "xxxxxxxxxx", "field": { "id": "xxxxxxxxxx", "name": "Your email address", "query-name": "email" }, "value": "tom.jordan@malcolm.support" } ] }

Question 7

Can I turn off automatic email alerts?

Accepted Answer

Malcolm! will automatically send you email alerts when certain activity happens on your instance, such as a user leaving feedback or a Workflow being completed. Wherever possible we aggregate these alerts so you receive fewer emails but if you'd rather not receive them you can easily turn them off.

To do this, from the MyMalcolm control panel area, click your name at the top of the screen where it says "Logged in as"

You'll then be taken to your personal preferences. If you select the "Notifications" tab on the left you'll be able to edit the notifications you receive. Remember to hit "Save" once you are done!

Note that your notificatons are based on an instance. If you are a user on more than one instance you should first switch to the instance you wish to adjust notifications for. You can do this using the drop down selector at the top right of the screen. You can therefore have different notification preferences for different instances. The notificiation preferences you choose are personal to you and will not affect the notifications of other team members on an instance.

Question 8

How do I use Malcolm! with my own domain or sub-domain?

Accepted Answer

You can use your own domain or sub-domain with Malcolm! There is no extra cost for doing this.

To set this up go to the Settings Section in MyMalcolm then Custom Domains. Enter your custom domain and you will be given instructions on how to verify domain control/ownership and set up your DNS. We can host on SSL too and we'll automatically generate a secure certifcate for you. Once again, there is no extra cost for doing this!

Once you have set up your custom domain or sub-domain both that and your malcolm.support / malcolm.app URL will work and serve content. If you don't want the .malcolm domains to work just select the redirect option and any traffic will be redirected.

Watch a video guide to setting uo your own domain below.

Question 9

How do I see completions of my Workflow?

Accepted Answer

When one of your customers completes a Workflow that is called a completion. You can review the data collected via MyMalcolm. Go to the Workflow Section and then select the Completions tab. You can also review completions for an individual Workflow by navigating to that Workflow via the Library and then selecting Completions.

You can export all the Completion data by selecting Exports within an individual Workflow.

Don't forget that you can also configure email notifications each time a Workflow is completed and use Integrations and Webhooks to pass collected data into other systems.

Question 10

How can I change my Hosted Hub URL?

Accepted Answer

You can change the URL of your Hosted Hub via the Settings Section of MyMalcolm. Go to Custom Domains and you choose a new URL on malcolm.support or malcolm.app here. The URL must be available ie not being used by another customer.

You can also configure your own external domain or sub domain in this area as well.

If you want to change the part of the URL after your domain please see this article.

How can we help?

Using Malcolm! and need help?

What do you think of Malcolm?

Most popular