Question 1

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 2

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 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](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 4

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 hash/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 hash/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 the hash.

```php
$data = file_get_contents('php://input');

$key = 'Your secret token';

$hash = hash_hmac('sha256', $data, $key);
```

Next encode the hash using a Base 64 encoder, in PHP this is [base64_encode](https://www.php.net/base64_encode).

```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. |
| completed-at | string | The date and time the Workflow Session was completed, in ISO 8601 format. |
| label |string | A descriptive label, which will include the name of the person who completed the Workflow if your Workflow contains name attributes. |
| 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. |
| text | string | An extended version of the label which also includes the Workflow name. |
| values | array[Value] | The submitted Workflow Values (if included). |
| workflow | object[Workflow] | The related Workflow. |

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",
  "completed-at": "2020-04-01T12:05:00+00:00",
  "label": "Completed by Tom Jordan",
  "locale": "en-GB",
  "started-at": "2020-04-01T12:00:00+00:00",
  "text": "Workflow \"Open Support Ticket\" was completed by Tom Jordan.",
  "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"
    }
  ],
  "workflow": {
    "id": "xxxxxxxxxx",
    "name": "Open Support Ticket",
    "published-at": "2020-04-01T09:00:00+00:00",
    "version": "Version 1"
  }
}
```

Question 5

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 6

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 7

How do I use Zapier to connect Malcolm! to other applications or services I use?

Accepted Answer

Malcolm! now plugs into [Zapier](https://zapier.com). Zapier is an integration platform - [it connects thousands of apps to other apps.](https://zapier.com/apps) Malcolm! plugs into Zapier

In the context of Malcolm! this means that when a Workflow is completed you can use our Zapier integration to route some or all of the data that has been collected from that Workflow through into Zapier and then in turn onto thousands of other apps or services. Here is how to set things up: 1. Firstly set up and publish a workflow in Malcolm! that collects the data you wish to move into other applications 2. In MyMalcolm go to the Settings Section, then Workflows, then Integrations, then click on Zapier Zapier in Malcolm! Integrations

3. Sign up for an account at [Zapier](https://zapier.com) if you don't already have one - it is free - or login if you do have an account. 4. In Zapier, click the "+" or choose one of the suggested Zaps ![Malcolm! on Zapier](https://malcolm-en-gb.s3.eu-west-1.amazonaws.com/instances/HwJyEPPI3q/resources/WZcsX7PoBM/screenshot-zapier.com-2021.02.08-12_32_31.png) 5. Your trigger app should be Malcolm! and you want it to trigger on a new Workflow completion so hit "Save + Continue" once you have selected this option 6. You now need to connect your Malcolm! instance to your Zapier account - click "Connect an Account" and follow the instructions. Once connected click "Save and Continue" 7. Choose a workflow then "Continue" 8. Wait for a sample to load and then click "Continue" 9. Choose an action App of your choice and configure as required - the exact process will vary from action App to action App but you are likely to need to agree some permissions and choose some options. Once done click "Save + Continue" or "Finish" 10. You will then be able to name your Zap and choose whether it is on or not 11. Back in MyMalcolm, if you find the Workflow you used in your Zap in the Library, select it, then go to Configure then Integrations you should be able to see Zapier 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). Remember that Malcolm! always stores your data (which you can download anytime) - so if Zapier 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 Zapier - we hope you are too! If you have questions or need a hand setting things up just [contact us](https://support.malcolm.support/workflows/submit-support-ticket) and we'll be happy to help.

Question 8

Understanding Malcolm! - some concepts and how to use the product

Accepted Answer

Malcolm! is a super powerful and flexible web based product but it might seem a bit confusing at first.  Here is a quick primer on some core Malcolm! concepts and features which we hope will help you understand the product and use it in the way that makes sense to you and your business.

**Core Components of Malcolm!**

Malcolm! has two core content components: ***Malcolm! FAQ*** and ***Malcolm! Workflow.***

Malcolm! FAQ is all about answering your user's questions and/or providing information (eg a how-to or a policy).  
Malcolm! Workflow is all about taking your users through tasks or procedures.

Before we created Malcolm! we spent a lot of time building online systems that helped companies digitise what they do.

We found that - in broad terms - this came down to designing and developing systems that: 
* answered questions and
* took users through a process.

**For example**

Lets say you sell and service industrial heating systems.  A potential customer might want to know if you service a particular type of boiler that they have in their office.

You can let that potential customer find the answer to that question themselves via Malcolm!.  You'd create a question along the lines of "Which types of boiler do you service?" and in your answer you'd include all the makes and models that you work with.

Your potential customer would come to your website, and be able to find the answer themselves using Malcolm!

Next, having learnt you do indeed service the boiler they have in their office they might want to book a service appointment.

To do this you are likely to need to know a few details - for example their name, their company name, where their office is and perhaps a few other details like their phone number and email, when they are available for a service visit, any issues they are having with the boiler and when it was last serviced.

You can create a form that asks all those questions in Malcolm! and add that form as a "Book a service" link onto your website.  When a customer fills that form in Malcolm! can email you all the details. Malcolm! can also do lots of other clever things like pass that request into other systems that you might use.

**Why would I want to do this?**

* **Customers like it** - nowadays more and more people prefer to do things online
* **You look professional and slick** - Malcolm! can integrate with your existing website and you can style all the screens to match your brand
* **It's available 24/7/365** - customers can find what they need at a time that suits them 
* **Save time** - stop burning time answering the same questions or doing the same process again and again
* **Consistency**- receive complete information from your customers in the format you need it
* **Efficiency** - pass customer information collected via Malcolm! into your other systems automatically
* **Get feedback** - Malcolm! let's your customers feedback to you whether the information they found was helpful or areas for improvement 
* **Analytics**- get statistics on what customers are searching for, what they are reading and the most popular times for certain types of requests
* **Great management tools** - You and your internal team / staff can see everything at a glance via MyMalcolm - the comprehensive control panel area of Malcolm!

[You can see some examples of possible uses of Malcolm! here](https://malcolm.app/examples)

**Use Malcolm! FAQs and Workflows together or separately**

One of the things to bear in mind is that you can use the FAQ and Workflows parts of Malcolm! together or individually.  It may be that you want to build a customer knowledge base using Malcolm! FAQ but you have no need for Workflows at the moment.  That is no problem! Similarly you might want to create a series of web forms for various user servicing tasks using Malcolm! Workflow but don't need to answer questions with FAQs.  Again this is no issue. You simply use the parts of Malcolm! that make sense to you and your business.

**How does Malcolm! work with my current website?**

At the heart of Malcolm! is flexibility.  We want to make it as easy as possible to work with our system.  We also want to offer options for a wide user base - from a one man band with no or limited web development knowledge through to big companies who may have large in house technical teams.

At one of the end of the scale is our Hosted Hub.  Every instance of Malcolm! comes with a hosted Hub.  This is a website that we host for you. You can customise it entirely to your requirements.  You can change the branding, the colours, the fonts, the layout, the copy, the icons etc etc.  You can even configure it to work on one of your own domains or sub domains.

If you don't have a current website your Hosted Hub could be your main website.  If you already have your main website at www.domain.com you could set up your fully branded Malcolm! Hosted Hub at a sub domain like support.domain.com or help.domain.com or customers.domain.com

Some customers may not wish to do this and instead may wish to integrate Malcolm! into their current website.  No problem!  We have a whole section in the MyMalcolm Control Panel dedicated to this and there a variety of ways you can bring content and functionality from Malcolm! into your own website.  We've also got a plugin for Wordpress and a variety of widgets and further integration options. Want a floating widget? No problem.  Want a button which opens a modal/overlay?  No problem.  Customers on our Enterprise plans can have full programmatic access to Malcolm! content and functionality via our comprehensive API.

**Don't forget your Internal Customers!**

Remember that your business or organisation may have more than one type of "customer!".  As well as using Malcolm! with members of the general public you can also use it internally to help a particular business function or department.

For example:
* In our example of being an industrial heating sales & service company above you could use an instance of Malcolm! for your service engineers. Various knowledge about things you service could be stored in Malcolm FAQ! and you could build digital versions of processes or business procedure in Malcolm! Workflow - for example job sheets or part order forms. 
* You could use Malcolm! as an online presence for your [Human Resources](https://malcolm.app/examples/human-resources) or [Finance department](https://malcolm.app/examples/finance)
* You could use Malcolm! as a way of [communicating information about your premises or facilities](https://malcolm.app/examples/commercial) 
* You could use Malcolm! as a home for an [internal project or initiative](https://malcolm.app/examples/internal)

Question 9

How can I listen to JavaScript events posted from embeds?

Accepted Answer

Malcolm! embeds fire events on user interactions such as when someone first reads an FAQ, completes a Workflow or performs a search. These events can be picked up on your web page for you to perform custom actions - for example creating an event for your Analytics. ## How can I listen to these events? The first event, `mapiload`, is fired on the `window` when the `mapi.js` library has loaded. ``` window.addEventListener('mapiload', function() { // mapi has loaded, waiting for embeds to render // ... }); ``` The embeds are then rendered followed by the `mapi.onrender` event. To register a listener use the `mapi.on` function. ``` window.addEventListener('mapiload', function() { // mapi has loaded, waiting for embeds to render mapi.on('render', function() { // Embeds rendered // ... }); }); ``` We recommend combining the `window.addEventListener` and `mapi.on` functions for maximum compatibility especially if your application uses JavaScript page transitions, however if your application reloads the page on each request you could combine these into one. ``` window.addEventListener('mapiready', function() { // Embeds rendered // ... }); ``` Once the embeds have rendered use the `embed.on` function to register listeners. If you know the ID of the embed (can be found in [MyMalcolm](https://my.malcolm.app)) use `mapi.findEmbed` function. ``` mapi.findEmbed('EMBED_ID').then(function(embed) { // Embed found embed.on('EVENT_NAME', function(data) { // Data returned from embed // ... }); }); ``` Alternatively loop through the `mapi.embeds` array. ``` mapi.embeds.forEach(function(embed) { embed.on('EVENT_NAME', function(data) { // Data returned from embed // ... }); }); ``` Putting it all together your code snippet could look something like this. ``` ``` ## What events are available? | Event name | Widget | Overlay | Inline | |:-----------------------------|:------:|:-------:|:------:| | `close` | ✔︎ | ✔︎ | ✘ | | `closed` | ✔︎ | ✔︎ | ✘ | | `faq-feedback-received` | ✔︎ | ✔︎ | ✔︎ | | `faq-read` | ✔︎ | ✔︎ | ✔︎ | | `faq-referral` | ✔︎ | ✔︎ | ✔︎ | | `loaded` | ✘ | ✘ | ✔︎ | | `open` | ✔︎ | ✔︎ | ✘ | | `opened` | ✔︎ | ✔︎ | ✘ | | `search` | ✔︎ | ✔︎ | ✔︎ | | `workflow-completed` | ✔︎ | ✔︎ | ✔︎ | | `workflow-feedback-received` | ✔︎ | ✔︎ | ✔︎ | | `workflow-referral` | ✔︎ | ✔︎ | ✔︎ | | `workflow-started` | ✔︎ | ✔︎ | ✔︎ |

Question 10

Can I remove the Malcolm! branding?

Accepted Answer

It is quick and easy to remove the Malcolm! branding and - if you want - replace it with your own. Here is how: **Hosted Hub** By default your Hosted Hub is Malcolm! branded. To change that: * In MyMalcolm go to the Brand section * Click "Themes" on the black sub navigation * The default Malcolm! theme will be selected. Click the "duplicate" icon (two squares overlapping). This will create a copy of the default theme called "Default copy" * Select the Default copy theme by clicking on it. Then click the "edit" icon (a pencil). * This brings up the edit theme interface. There are a huge amount of things you can change here. Use the left hand vertical navigation to browse all the possibilities. MyMalcolm Theme Editing Options

**Footer** Be default a "powered by Malcolm!" badge appears at the bottom of content. You can turn this off (and also add other footer content such as copyright notices etc) in the "Footer" section of the edit theme interface referenced above. **Embeds** You can turn off the "powered by Malcolm!" badge in your embeds by turning off the footer. You do this via the style section of your embed configuration. Style controls in an Embed in MyMalcolm

**Domain** Finally don't forget you can easily configure Malcolm! to use your own domain or sub-domain. [For further details see this article.](https://support.malcolm.support/faqs/how-do-i-use-my-own-domain-or-sub-domain)

How can we help?

Using Malcolm! and need help?

What do you think of Malcolm?