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!](https://support.malcolm.support/faqs/how-do-i-write-a-good-frequently-asked-question-faq) Compose FAQ in MyMalcolm

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. Configure FAQ in MyMalcolm

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

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](https://malcolm.app/examples)

**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 3

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.

![Screenshot 2021-01-26 at 16.17.46.png](https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/IWqLLH7kgn/Screenshot%202021-01-26%20at%2016.17.46.png)

### 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
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](https://www.php.net/hash_hmac) function to generate a binary hash.

```php
$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](https://www.php.net/base64_encode) function.

```php
$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](https://www.php.net/manual/en/reserved.variables.server.php) variable to access the headers.

```php
$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 | string | A string representation of 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 4

How do I embed content from Malcolm! into my own website or app?

Accepted Answer

You can easily embed content from Malcolm! into your existing website, app, product or online service with just a few lines of code. Begin by going to the Share section of MyMalcolm and then select Embed. Choose your embed type in MyMalcolm

We offer the following type of embeds: * **Floating Widget** (with button and draw options) - this option floats a button or drawer “pre-expand” over your site, application, product or service - when clicked a content panel opens up * **Overlay / Pop Up** - this opens an overlay / popup over whatever the user is currently seeing - it’s triggered by a link you can place wherever you want in your site, application, product or service * **Inline** - pull content directly into the same pages/screens your users are seeing with this option - use blend mode for a truly seamless experience! * **Full Page** - finally this option replaces your entire page content with Malcolm! content - this can be useful in certain scenarios, for example if you are using a CMS and want to totally replace the content with Malcolm! content on a container page you create. Choose your embed content in MyMalcolm

In terms of the type of content you can embed options include: * **Hosted Hub results** - paginated results showing the default filtered FAQs and Workflows as seen on your Hosted Hub homepage * **A single FAQ** - your choice of FAQ * **A single Workflow** - your choice of Workflow * **Author listing** - paginated results showing FAQs from a particular author * **Category listing** paginated results showing FAQs within a partiuclar category * **Filtered results** paginated results showing FAQs and Workflows filtered by your choice of filter (eg most popular, most recent, most helpful etc) * **Search results (contextual)** - paginated results showing FAQs and Workflows according to a search query provided via a meta tag on your page * **Search results (specified search query)** - paginated results showing FAQs and Workflows according to a given search query * **Tag listing** - paginated results showing FAQs referenced by particular tag Note that if you just want to embed a single FAQ or Workflow you can also access a quick embed interface via the Library in both the FAQ and Workflow sections of MyMalcolm. Simply select "Embed" from the menu accessible on the right hand side of the respective published FAQ or Workflow. You can configure various options around the visual stlye of your embed. The exact options available depend on the type of embed you have chosen. When you have finished configuring the content and visual appearence of your embed, Malcolm! will give you the code that can be used to pull your content into your website, app, product or online service. Watch a video guide to embeding Malcolm! content into your website below.

Question 5

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! Domain Settings

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 6

Do you support animated GIFs?

Accepted Answer

Yes you can use animated GIFs in Malcolm! placing them in your FAQs or in Workflows (via the Content element).

You can upload the animated GIF into the media section of MyMalcolm or you can pull in externally hosted GIFs.

This cat has been uploaded to MyMalcolm:  
<img alt="Animated Cat.gif" src="https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/WsOiR3iaEG/Cat.gif">

To pull in external GIFs use the following Markdown syntax: 
`![Image Description](https://media.giphy.com/media/QpWDP1YMziaQw/source.gif)`

The above Markdown results in this:

![Image Description](https://media.giphy.com/media/QpWDP1YMziaQw/source.gif)

Have fun!

Question 7

How do I build a Workflow?

Accepted Answer

You can build a Workflow quickly via the Workflow Builder in MyMalcolm. To get started, first go to the Workflow section of MyMalcolm and then click "Create a Workflow" towards the top right of the screen. Workflows: How would you like to start?

You can then choose whether to build a Workflow from scratch, start with one of our templates or - if you have already created some Workflows previously - clone one of those previously created Workflows. You can then use our drag and drop builder to create your Workflow.

Our Workflow builder enables you to: * Drag and drop question elements onto your form * Customise those question elements * Configure Filters, Validators and Rules * Split forms over multiple pages * Customise page titles and progress bars * Customise thank you page Once you have created the content of your form, you can to the Configure tab and configure various options including setting up email notifications or Integrations. Configure your Workflow

By default your Workflow is created as a web form that you access via a URL. But you can also surface that Workflow in a variety of other ways (including float it over page in a widget, via a modal/overlay launched by a button you place on a site, or via embeds or plugins) - take a look at the Share section of MyMalcolm to do this. Watch a video guide to building a Workflow below.

Question 8

How do I write a good Frequently Asked Question (FAQ)?

Accepted Answer

Some top tips for writing a good Frequently Asked Question (FAQ) include:

* Think like your customers and try to phrase your title in a way a real customer would ask you a question

* Use the brief summary area to provide the initial answer - this is what customers will see in search results and when browsing FAQs

* For the full answer you can repeat the Brief Summary information but go into more detail

* Try and be concise and punchy with your answer - it can be useful to break up the text with subheadings and bullet points

* Don't repeat information if it's available elsewhere - better to link to that information! For example if you have an FAQ answering "What times are you open?" and your opening hours are on your main website your answer can simply be "Our opening hours can be seen on our website here" and you can add a link

* If you have images or media (eg a YouTube video) that can help with an answer don't be afraid to include it in your answer - Malcolm! fully supports this and customers love it!

* Remember to use tags and categories as that will help your customer find their way to the FAQ

* Use the feedback option in Malcolm! as that will let customers tell you if the content is useful or not. Regularly review the feedback you get in MyMalcolm!

Question 9

Can I change the order in which FAQs are shown when a user browses a category, tag or author listing?

Accepted Answer

You can change the order your FAQs are sorted in when your users view by author, category or tag via Settings --> FAQs --> General. ![Author, category and tag sort order in MyMalcolm](https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/evapRB3yn5/screenshot-my.malcolm.app-2021.06.29-16_30_20.png) In addition to this you can also set an absolute order for FAQs within a particular category. To do this go to the category in question in FAQs --> Categories and select Reorder. You can then drag the FAQs to create the order you want. ![Reorder the FAQs in a category in MyMalcolm](https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/RibhVyjiBt/Screenshot%202021-10-11%20at%2010.40.21.png) Note that these settings only affects listings, not searches. Searches are ordered by relevance. If you want to be able to set an absolute for FAQs within an author or tag listing the way to do this is to set the date sort option, then in the individual FAQ configure tab use the display date to determine an order. The FAQ with the most recent date will be shown first in an author, or tag listing - and also in a category listing unless overridden using the absolute method above. The FAQ with the second most recent date will be shown second and so on. ![Display date in FAQ configure tab](https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/44K839GO3Z/screenshot-my.malcolm.app-2021.06.30-15_14_49.png) Note that if you set the display date to invisible either globally in Settings or individually on an FAQ's configure tab the date won't show on the front end to your customers/users but the date you set will still be relevant in determining the order in which the FAQs displays. See the video below for a walkthrough

Question 10

What is a Workflow?

Accepted Answer

A Workflow is a web based form that your customers complete.  You can build these forms quickly in MyMalcolm and use them to create a digital version of a business process.

**For example**
* A contact form
* A survey
* A customer enquiry
* A new customer details form

You can build everything from simple single screen journeys through to more complex multi-step journeys with conditional routing (ie offering certain choices based on previous answers).

Malcolm! automatically stores all data - including abandoned forms.  You can export this data at any time.   You can also pass that collected data through to other systems via Integrations or Webhooks.

How can we help?

Using Malcolm! and need help?

What do you think of Malcolm?