Manifest Reference

Sample Add-on Manifest

{
  "name": "Hello World Addon",
  "version": "1.0",
  "iconURL": "https:\/\/www.servicem8.com\/images\/addon-sdk-sample-icon.png",
  "supportURL": "https:\/\/support.exampleaddon.com",
  "supportEmail": "support@exampleaddon.com",
  "oauth": {
    "scope": "create_jobs create_clients"
  },
  "actions": [{
    "name": "Hello Action",
    "type": "online",
    "entity": "job",
    "iconURL": "https:\/\/www.servicem8.com\/images\/addon-sdk-sample-icon.png",
    "event": "hello_world_event",
    "location": "modal"
  }],
  "menuItems": [{
    "name": "Hello Menu",
    "type": "addon",
    "iconURL": "https:\/\/www.servicem8.com\/images\/addon-sdk-sample-icon.png",
    "event": "hello_world_event"
  }],
  "webhooks": [{
    "object": "job",
    "fields": [
      "job_address",
      "billing_address"
    ]
  }]
}

JSON Parameters

name

The name of your Add-on

version

The version of your add-on, you should increase your version number with each release of your add-on to the store.

iconURL

A publicly accessible image url where your add-on icon is available. This icon will be used for your add-on within the ServiceM8 Add-on Store. Icon will automatically be resized down to required size so we recommend an icon size of at least 512x512px.

supportURL

A URL where ServiceM8 customers can visit if they need support using your add-on.

supportEmail

An email address where ServiceM8 customers can get in contact if they need support using your add-on.

oauth[scope]

If you are using Serverless OAuth, ServiceM8 will complete the OAuth flow between clients and your add-on during activation. Specify your OAuth scope here as a space-separated list of scope requirements. This setting will determine what API scope your STS access token is issued with.

actions

Actions are an Add-on capability to add new buttons to the Job Card or Client Card. Actions are not mandatory, and a single add-on can include many actions if required.

actions[name] Mandatory

Name is the name that will be displayed to the user for the new action in either the web platform or app.

actions[type] Mandatory

Type is the type of action you wish to create. If you wish to support multiple types, add several action records to your manifest. Valid values are:

• online: Your add-on action will appear in the online web platform job/client cards
• app: Your add-on action will appear in the app job/client cards

actions[entity] Mandatory

Entity is which card you wish to extend with your action. If you wish to support multiple entities, add several actions to your manifest. Valid values are:

• job: Your add-on action will appear in the Job card
• company: Your add-on action will appear in the Client card

actions[iconURL] Mandatory

A publicly accessible image URL for the action icon. This will appear inside the job/client card for users. Icon should relate to the action that will be undertaken to give users context of what action they are taking. Icon will automatically be resized down to required size so we recommend an icon size of 256x256px.

actions[event] Mandatory

The event name to be invoked on your add-on backend (lambda or web-service). Event context is provided automatically (job, company, account, etc) as part of the invoked request.

📘

It's good practice to always use lower case event names, as your function will receive the event name in lower case. Using lower case in the original event name will prevent confusion.

actions[location]

Location is only supported on web platform, app always uses window. Defaults to modal for online actions, and window for app actions.

Location is where your action should be presented to the user. Valid values are:

• modal: Your action will be presented in a popup window, inside the ServiceM8 UI
• window: Your action will be presented in a new tab/window, outside the ServiceM8 UI
  Use only when linking the user to a second app/UI, otherwise modal is recommended.

menuItems

Menu Items are an Add-on capability to add new ServiceM8 menu items to the web platform (under the Addons menu), or to the ServiceM8 app (under the More menu). Menu Items are not mandatory, and a single add-on can include many menu items if required.

menuItems[name] Mandatory

Name is the name that will be displayed to the user for the new menu item in either the web platform or app.

menuItems[type] Mandatory

Type is the type of menu item you wish to create. If you wish to support multiple menu items, add several menuItem records to your manifest. Valid values are:

• addon: Your menu item will appear in the online Addons menu
• app: Your menu item will appear in the app more tab menu

menuItems[iconURL] Mandatory

A publicly accessible image URL for the menu icon. Icon should relate to the action that will be undertaken to give users context of what action they are taking. Icon will automatically be resized down to required size so we recommend an icon size of 256x256px.

menuItems[event] Mandatory

Each action must provide either an event or an actionURL

📘

It's good practice to always use lower case event names, as your function will receive the event name in lower case. Using lower case in the original event name will prevent confusion.

The event name to be invoked on your add-on backend (lambda or web-service) when users clicks on the menu item.

webhooks

Webhooks enable your add-on to subscribe to changes in account data, by specifying an object and which object fields are relevant you will receive webhook_subscription to allow you to take event-based actions. Webhooks are optional within a manifest. You should always subscribe to the minimal object/field combination that meets your requirements, as each change will invoke your addon for processing.

webhooks[object] Mandatory

The object you wish to subscribe to for change notifications. Objects are the same as API Endpoints - so review API documentation for available endpoints for subscription.

webhooks[fields] Mandatory

An array of fields you wish to be notified if any changes occur. Fields that can be subscribed to match the API endpoints - so review API documentation for available objects/fields for subscription.