Introduction

Blueprints allow you to add custom order steps to the different order types in Encapto MSP. See the order types documentation to understand the different order type life-cycles.

Just like the built in steps, Blueprint steps can be automated (e.g. web hooks) or manual (for you or your staff to fulfil).

This enables things like:

• Registering the customer in your other systems
• Custom provisioning steps for any hardware or services you sell
• Further tailoring in provisioned hardware and services (e.g. enabling ports on a device on allocation)
• Sending notifications

Blueprint steps are automatically added to matching orders and are visible in the order details with all the regular steps.

 

How to add blueprint steps

1. Navigate to “Blueprints” on the left hand side menu
2. Select the phase the blueprint is applicable for (see the phase descriptions below)
3. Click “Add action”
4. Fill in the form with the step type, and various filter and specific step options. See below for a description of all the fields.
5. Click “Save”

 

Phases

The phase controls the type of orders the Blueprint step will run against. This affects both when the step runs, as well as the information available to the step. Some steps are only available for particular phases.

 

Creation Phase

Blueprint steps added to the “creation” phase will run for orders that provision new hardware or services to new or existing customers. These steps have access to the new inventory being provisioned and the target customer, but they do not have access to the site that the inventory may be then allocated to.

Examples of steps that may defined here:

• Registering the customer into other systems (e.g. billing / accounts)
• Raising purchase orders / invoices
• Manual provisioning / setup steps for custom hardware and services

 

Allocation phase

Steps in this phase run when the hardware or services are allocated into a specific site. The steps have access to the inventory being allocated to the site, as well as the site itself.

Examples of steps that may defined here:

• Configurations that can only occur after a device is put into a site, e.g. enabling ports
• Manual steps required to activate custom hardware or services to a specific site

 

Unallocation phase

Steps in this phase run when the hardware or services are unallocated from a specific site. These steps typically perform any clean-up required from allocation phase steps. For instance, if there was a custom step to activate a service for a specific site on allocation, this would deactivate that service on unallocation.

Examples of steps that may defined here:

• Reversal of allocation blueprint steps, e.g. de-activate custom hardware or service from a specific site

 

Step types

 

Manual Tasks

Manual task steps will stop the order processing and await manual input. If configured, this will also send out an email notification.

These steps can be used as a work-flow mechanism to update third party systems or any other tasks where automation is not an option.

Description Field

Detailed description of what needs to be done. This is shown in the step pop-up when being actioned.

 

Webhooks

Webhooks will callout to external systems with a predefined payload, allowing custom, automated integrations to be added to the provisioning flow.

 

 

Security

It is very important that security is considered when implementing web-hooks. The following measures are recommended as a minimum:

1. Only https URLs can be used as web hooks.

2. Encapto MSP will put the 'secret key' value in the request header as 'x-encapto-msp-token' - this secret must not be shared and should be validated by the web hook handler to ensure requests are legitimate.

3. The request payload (see below) intentionally contains minimal information (and no sensitive information). It is expected that the web hook handler will use the Encapto MSP API with its own credentials to look up details of the supplied uuids.

4. IP whitelisting is highly recommended to ensure only Encapto MSP can call your endpoint - our IP addresses are:

use1 cluster: 35.229.101.193, 104.196.160.60, 34.74.84.247

euw1 cluster: 34.79.222.190, 34.140.151.110, 34.79.52.62

 

Request Payload

Encapto MSP will call the configured webhook with the following payload:

Header:

x-encapto-msp-token: xxxx-xxxx-xxx 

# the webhook handler should validate that this secret matches the secret configured
# in Encapto MSP blueprint, to ensure that the caller is actually Encapto MSP.

Body:

    

name: "" # The name of the webhook
actionUuid: "" # unique uuid for this action/webhook.

# Custom fields set on the order.
customFields: [] # list of field names and values.

stepUuid: "" # a uniquely generated order step uuid for each webhook call.
# Useful if there is a network failure and Encapto MSP retries the payload.
# if the request with this uuid was previously successfully processed, then 
# you can skip processing the message

correlationId: "" # our system generated uuid for this event. 

# when a webhook fails, and we retry it, the retry info goes in herehere
failureCount: 2 # number of times the request has failed.
lastRun: timestamp 
error: obj # an error object containing the last error response.

# Entity uuids - use Encapto MSP uuids to lookup the order/company/site details.
orderUuid: "uuid" 
companyUuid: "uuid" 
siteUuid: "uuid" # (if applicable.)

    

 

Response Payload

# Response object all parameters are optional an empty response is success (nothing to do)
stepStatus: "skipped" # defaults to completed.
stepMetadata: [] # array of objects {name, text} to be displayed in the step.
    

 

Testing Webhooks and advanced functionality

A test account can made available to test web hook functionality end to end. Our web-hooks can provide advanced integration functionality, including the ability to add entities, modify permissions and more. Contact our support team for assistance.

 

 

Filters and Fields

Filters further refine whether a step is included in an order or not - as well as it’s position in the order steps list (e.g. which step it runs before or after). Note that not all step types have these options available.

 

When …

This controls whether the step is included in the order steps or not depending on the associated inventory in the order. Select ‘anything’ to always include the step, otherwise you can select multiple inventory items that this step is applicable to. The step will only be included in the order if one or more of those items are in the order.

 

Step Title

A short description of the step. Shown in the step list of the order detail view:

And in the order modal pop-up when actioned from the order queue list:

 

Step Status

One or two word summary that represents the order status when awaiting completion of this step. E.g. “awaiting procurement” or "tea time". This is shown in the order queue list in the status column:

 

 

 

Recurrence

This controls whether the step needs only to be run “once” or “always”. A step with “once” will only run a single time for that customer / site in the relevant phase, whereas "always" will run every time.

For instance, a step to register the customer into another CRM system may have “recurrence” set to “once” - as you only need to register the customer once. Any further purchases they make do not need to be updated into that system.

On the other hand, if the step is for procurement, then it may have the “recurrence” set to “always” - each time the customer buys X, it needs to go through procurement.

In the allocation and unallocation phases the recurrence is tracked against the site level instead of the customer.

For instance, if there is a step that sets a default SSID name on the wireless network on allocation, it should have a recurrence set to “once”. That way, if the customer later changes the SSID and then purchases another wireless access point, the SSID name does not reset back, overriding their changes.

 

Step Order

Order steps are run in sequential order, this can be seen on the order details page. The “step order” field allows control on when the step will be run in relation to other steps.

For instance, a step to register the newly created Meraki organistion for the customer in another system would need to run “After Meraki setup”. Whereas a step to procure the items may need to happen “Before Meraki setup”.

 

Advanced Expressions

Some blueprint steps allow for advanced expressions - this allows for very powerful automation - but that comes with quite a bit of complexity. We recommend that you contact Encapto support to help configure these expressions. Under the hood - the filtrex is used to parse the expressions.

 

As the values are expressions and not values - you will need to double quote strings values (e.g. "Bob's Cafe")

 

You can also use the following extensions:

	Type	Description
_NOT_SET_	Constant	Use "_NOT_SET_" to exclude particular fields. This is used in blueprint steps that have fields that should only be specified in certain circumstances.
_REMOVE_ENTRY_	Constant	Similar to _NOT_SET_, however this will remove an entire entry (as opposed to just the field). This is typically used in an array of objects, if the object in the array has a field set to "_REMOVE_ENTRY_" then it will not be included in the array.
siteEntityLookup(siteName, entityType, path)	Function	This will look up information from an entity under another site. If siteName is blank, then the function will return "_NOT_SET_". For instance, when configuring a VPN between two sites, you can lookup the ID of another site by: siteEntityLookup("Other Site Name", "meraki-combined-network", "configuration.networkId")
customFields.Field_Name	Constant	Custom field data is available via the 'customFields' property. Note that custom field names will have "_" instead of spaces in their name. E.g customFields.Hub1_Site_Name
randomPassword(length)	Function	Creates a randomised password with the given length. Generated password are suitable for SSID, ambiguous characters are avoided (e.g. lower case L, O vs 0 etc),