Building a Custom Availability Provider Lambda function

Custom Availability Providers (CAPs) are configured with a JSON-based request and response protocol that is written in a well defined JSON schema. A Lambda function will parse the request and provide a valid response.

Request and response elements

Request elements

The following is a sample request used to configure a CAP for an Amazon WorkMail user:

{
    "requester": {
        "email": "user1@internal.example.com",
        "userName": "user1",
        "organization": "m-0123456789abcdef0123456789abcdef",
        "userId": "S-1-5-18",
        "origin": "127.0.0.1"
    },
    "mailboxes": [
        "user2@external.example.com",
        "unknown@internal.example.com"
    ],
    "window": {
        "startDate": "2021-05-04T00:00:00.000Z",
        "endDate": "2021-05-06T00:00:00.000Z"
    }
}

A request is composed of three sections: requester, mailboxes, and window. These are described in the following Requester, Mailboxes, and Window sections of this guide.

Requester

The requester section provides information about the user who made the original request to Amazon WorkMail. CAPs use this information to change the behavior of the provider. For instance, this data can be used to impersonate the same user on the backend availability provider or certain details can be omitted from the response.

Mailboxes

The mailboxes section contains a comma separated list of email addresses of users for which availability information is requested.

Window

The window section contains the time window which the availability information is requested for. Both startDate and endDate are specified in UTC and are formatted according to RFC 3339. Events aren't expected to be truncated. In other words, if an event starts before the defined StartDate, the original start will be used.

Response elements

Amazon WorkMail will wait for 25 seconds to get a response from the CAP Lambda function. After 25 seconds, Amazon WorkMail will assume the function has failed and generate failures for the associated mailboxes in the EWS GetUserAvailability response. This will not cause the entire GetUserAvailability operation to fail.

The following is a sample response from the configuration defined at the beginning of this section:

{
    "mailboxes": [{
        "mailbox": "user2@external.example.com",
        "events": [{
            "startTime": "2021-05-03T23:00:00.000Z",
            "endTime": "2021-05-04T03:00:00.000Z",
            "busyType": "BUSY"|"FREE"|"TENTATIVE",
            "details": {  // optional
                "subject": "Late meeting",
                "location": "Chime",
                "instanceType": "SINGLE_INSTANCE"|"RECURRING_INSTANCE"|"EXCEPTION",
                "isMeeting": true,
                "isReminderSet": true,
                "isPrivate": false
            }
        }],
        "workingHours": {
            "timezone": {
                "name": "W. Europe Standard Time"
                "bias": 60,
                "standardTime": {  // optional (not needed for fixed offsets)
                    "offset": 60,
                    "time": "02:00:00",
                    "month": "JAN"|"FEB"|"MAR"|"APR"|"JUN"|"JUL"|"AUG"|"SEP"|"OCT"|"NOV"|"DEC",
                    "week": "FIRST"|"SECOND"|"THIRD"|"FOURTH"|"LAST",
                    "dayOfWeek": "SUN"|"MON"|"TUE"|"WED"|"THU"|"FRI"|"SAT"
                },
                "daylightTime": {  // optional (not needed for fixed offsets)
                    "offset": 0,
                    "time": "03:00:00",
                    "month": "JAN"|"FEB"|"MAR"|"APR"|"JUN"|"JUL"|"AUG"|"SEP"|"OCT"|"NOV"|"DEC",
                    "week": "FIRST"|"SECOND"|"THIRD"|"FOURTH"|"LAST",
                    "dayOfWeek": "SUN"|"MON"|"TUE"|"WED"|"THU"|"FRI"|"SAT"
                },                
            },
            "workingPeriods":[{
                "startMinutes": 480,
                "endMinutes": 1040,
                "days": ["SUN"|"MON"|"TUE"|"WED"|"THU"|"FRI"|"SAT"]
            }]
        }
    },{
        "mailbox": "unknown@internal.example.com",
        "error": "MailboxNotFound"
    }]
}

A response is composed of a single mailboxes section which consists of a list of mailboxes. Each mailbox for which availability is successfully obtained is composed of three sections: mailbox, events, and workinghours. If the availability provider has failed to obtain availability information for a mailbox, the section is composed of two sections: mailbox and error. These are described in the following Mailbox, Events, Working Hours, Timezone, Working Periods, and Error sections of this guide.

Mailbox

The mailbox section is the email address of the user found in the mailboxes section of the request.

Events

The events section is a list of events that occur in the requested window. Each event is defined with the following parameters:

Working Hours

The workingHours section contains information about the the mailbox owner's working hours. It contains two sections: timezone and workingPeriods.

Timezone

The timezone subsection describes the mailbox owner's time zone. It's important to correctly render the user's working hours when the requester works in a different time zone. The availability provider is required to explicitly describe the time zone, rather than using a name. Using the standarized time zone description helps avoid time zone mismatches.

You must either define both standardTime and daylightTime, or omit both. Fields in the standardTime and daylightTime object are:

Working Periods

The workingPeriods section contains one or more working period objects. Each period defines a start and end of working day for one or more days.

Error

The error field can contain arbitrary error messages. The following table lists a mapping of well known codes to EWS error codes. All other messages will be mapped to ERROR_FREE_BUSY_GENERATION_FAILED.

Granting access

Run the following Lambda command from the AWS Command Line Interface (AWS CLI). This command adds a resource policy to the Lambda function that parses the CAP. This function allows the Amazon WorkMail availability service to invoke your Lambda function.

aws lambda add-permission \
    --region LAMBDA_REGION \
    --function-name CAP_FUNCTION_NAME \
    --statement-id AllowWorkMail \
    --action "lambda:InvokeFunction" \
    --principal availability.workmail.WM_REGION.amazonaws.com \
    --source-account WM_ACCOUNT_ID \
    --source-arn arn:aws:workmail:WM_REGION:WM_ACCOUNT_ID:organization/ORGANIZATION_ID

In the command, add the following parameters where indicated:

Example of Amazon WorkMail using a CAP Lambda function

For an example of Amazon WorkMail using a CAP Lambda function to query an EWS endpoint, see this AWS sample application on the Serverless applications for Amazon WorkMail GitHub repository.