Functions for ServiceM8 Add-ons take input in the form of data about an event that has happened, and produce output which is HTML and Javascript to be rendered in the ServiceM8 UI.

Events may be generated by the user clicking an Action button that your add-on has created in the web interface or in the mobile app (refer to the actions parameter of the Manifest Reference), or from changes to field values in ServiceM8 records such as Jobs or Clients (refer to the webhooks parameter of the Manifest Reference).

Input Provided

When an event happens, ServiceM8 invokes your Lambda function or callback URL with details about the event. For Lambda functions, this is provided as the event argument to your handler function. For web service callback URLs, the event object will be provided as a JSON Web Token (JWT) sent in the HTTP request body.

The event object has the following properties:

Property	Description
eventVersion	Addon SDK version, currently `1.0`
eventName	If the event was generated from an action* specified in your add-on manifest, this will match the event parameter of that action.* If the event was generated from a webhook specified in your app manifest, the value will be `webhook_subscription`
auth.accountUUID	The UUID of the ServiceM8 account which generated this event. The Account UUID is always the UUID of the single record returned by the Vendors endpoint on the REST API.
auth.staffUUID	The UUID of the Staff member who generated this event.
auth.accessToken	Provided to Lambda Functions Only If your addon requested OAuth scopes, this parameter contains an OAuth access token issued by the Secure Token Service, which your app can use to make authenticated requests to ServiceM8 APIs to read and write data. Your addon receives a new access token every time your Lambda function is invoked.
auth.accessTokenExpiry	The expiry time in seconds of your OAuth access token.
eventArgs	See table below

eventArgs for action events

Action events occur when the user clicks a button in the Job Card or Client Card that was created by the actions section of your add-on's manifest.

Property	Description
eventArgs.jobUUID	The UUID of the Job that is being viewed by the user.
eventArgs.companyUUID	The UUID of the Client that is being viewed by the user

eventArgs for webhook events

Webhook events occur when a field value changes on a record for which a webhook is registered in the webhooks property of your add-on's manifest.

Property	Description
eventArgs.object	The Object type whose field value changed (e.g. "job").
eventArgs.entry	An array of records that changed. This array always contains one element.
eventArgs.entry[0].uuid	The UUID of the record whose field value(s) changed.
eventArgs.entry[0].changed_fields	A list of fields that changed for which your add-on has requested to be notified.
eventArgs.entry[0].time	The UTC timestamp at which the field value(s) changed.
eventArgs.resource_url	URL at which the full record can be retrieved.

Example event argument for an Action

This is an example of the event argument which would be provided to your Lambda function or callback URL when a user clicks your add-on's button from the Job Card.

{
    "eventVersion":"1.0",
    "eventName":"hello_addon_event",
    "auth": {
        "accountUUID": "5e32b1f1-bb9f-457a-a67c-44dd7ff8ac1b",
        "staffUUID":"9d914a06-221e-4013-8b4d-2735272710eb",
        "accessToken":"9cd88543362a447291cfc362e3ce86f73d94eb2d",
        "accessTokenExpiry":900
    },
    "eventArgs": {
        "jobUUID":"0686ce69-4a5d-4f73-ad56-827ffaaced2b"
    }
}

Example event argument for a Webhook

This is an example of the event argument which would be provided to your Lambda function or callback URL when a job record's status field changes, and your add-on's manifest has registered a webhook to be notified of changes to that field.

{
    "eventVersion":"1.0",
    "eventName":"webhook_subscription",
    "auth": {
        "accountUUID": "5e32b1f1-bb9f-457a-a67c-44dd7ff8ac1b",
        "staffUUID":"9d914a06-221e-4013-8b4d-2735272710eb",
        "accessToken":"9cd88543362a447291cfc362e3ce86f73d94eb2d",
        "accessTokenExpiry":900
    },
    "eventArgs": {
        "object":"job",
        "entry": [{
            "uuid":"0686ce69-4a5d-4f73-ad56-827ffaaced2b",
            "changed_fields":["status"],
            "time":"2017-01-01 12:21:12"
        }],
        "resource_url":"https://api.servicem8.com/api_1.0/Job/0686ce69-4a5d-4f73-ad56-827ffaaced2b.json"
    }
}

Output Required

For Webhook events, no output from your function is required. Any return value provided in response to Webhook events will be ignored. The only requirement is that your function completes its processing and returns before the timeout expires.

For Action events, i.e. events generated when a user clicks one of your add-on's buttons in the ServiceM8 UI, your function must return HTML and javascript to be rendered inside a window in the ServiceM8 UI. This will be rendered inside an iframe, so it must be a complete HTML document including <html>, <head> and <body> tags. Refer to the Examples to see how to render appropriate HTML.

You can use javascript contained in your returned HTML to implement client-side functionality such as resizing or closing your add-on's popup window. Refer to the Client API documentation for more information.