Outlook

Warning

This data source is deprecated and not available for use. This document remains viewable for legacy support and archival purposes.

If necessary, consider connecting to this service using a REST data source instead.

Outlook encompasses several of Microsoft’s productivity and business tools. And with Office365—Microsoft’s cloud-based portal—Skuid can access Outlook email, calendar, tasks, contacts, and attachments with its own pre-configured data source type.

Configuration

In Azure Active Directory

Configure an Azure Active Directory (AD) app registration and configure its API permissions.

Within the Exchange section beneath Supported legacy APIs, select the following:

  • Under Calendars
    • Calendars.ReadWrite.All - Read and write user and shared calendars
    • Calendars.ReadWrite.Shared - Read and write user and shared calendars
  • Under Contacts
    • Contacts.ReadWrite.All - Read and write user and shared contacts
    • Contacts.ReadWrite.Shared - Read and write user and shared contacts
  • Under Mail
    • Mail.ReadWrite - Read and write user mail
    • Mail.ReadWrite.All - Read and write user and shared mail
    • Mail.ReadWrite.Shared - Read and write user and shared mail
    • Mail.Send - Send mail as a user
  • Under Tasks
    • Tasks.ReadWrite - Create, read, update and delete user tasks
    • Tasks.ReadWrite.Shared - Create, read, update and delete all tasks a user has access to

In Skuid

Create an authentication provider

With your app registration fully configured within Azure AD, you’ll now use the credentials you copied down earlier to create your Skuid authentication provider for Outlook.

  1. Navigate to Configure > Data Sources > Authentication Providers.

  2. Click New Authentication Provider.

  3. Fill out the necessary fields:

    • Name: Enter a unique name, such as OutlookAuth.

    • Authentication Method: OAuth 2.0 / OpenID

    • Provider Type: Outlook

    • Grant Type: Authorization Code

    • The Authorize and Token Endpoint URLs will be set automatically by the provider type.

    • Default Scopes: If not auto-populated, insert the following:

      • https://outlook.office.com/mail.send,https://outlook.office.com/mail.readwrite.all,https://outlook.office.com/calendars.readwrite.all,https://outlook.office.com/tasks.readwrite.all

      Note: do not add spaces.

    • Client ID: Enter your Azure AD app’s Application ID from the previous section.

    • Client Secret: Enter your Azure AD app’s key value from the previous section.

  4. Click Save.

  5. If Skuid asks you to create a Remote Site Setting, click OK.

Create a data source

With the authentication provider configured, now create a data source that uses it to authenticate and gain access to Outlook data.

  1. Navigate to Configure > Data Sources > Data Sources.
  2. Click New Data Source.
  3. Select the Outlook data source type.
  4. Enter a unique name for your data source, such as Outlook.
  5. Click Next Step.
  6. Select the authentication provider you created in the previous section.
  7. Click Save new Data Source.
  8. If Skuid asks to create a Remote Site Setting, click OK.

You can now select your Outlook data source within a model in the Composer.

Using the Outlook data source

The Outlook data source type is configured to access calendars, tasks, email, contacts, and attachments, so there are model entities related to each. One thing they have in common: their conditions can all accept OData system queries as condition parameters. Several of them also feature these queries as default conditions.

Let’s separate them by the service they facilitate.

Warning

At runtime, end users will see a standard OAuth popup to log into their Office365 account. Logging in and out of multiple accounts is not recommended and will cause unexpected behaviors.

Calendar

Using the Outlook data source, you can bring all Outlook calendars and events into your Skuid pages through two entities:

Calendar: This entity will load data on all calendars the end user has access to.

Fields

  • Id: (Default) The alphanumeric ID of a calendar. Within a Skuid page, you’ll use this value to set any conditions related to events.
  • Name: (Default) The user-friendly name of the calendar

Conditions

No conditions can be set for this entity.

Event: This entity will return a list of specific calendar events

Fields

  • Id: (Default) The alphanumeric ID of an individual event.
  • Subject: (Default) The name of the individual event.

Conditions

The following default conditions are available for the event entity:

  • $top: Determines how many records will be loaded into this model, “the top X number of records.” Related to the $top OData query option.
  • calendarId: The identifier of the calendar to be accessed (see Calendar entity, above). By default, this condition is set to primary, and displays the events of the individual currently logged in.
  • startdate: Determines how far back in time the model will query for events. By default this condition looks back 5 weeks.
  • enddate: Determines how far in the future the model will query for events. By default this condition looks forward 5 weeks.

The event entity actually contains the details of your calendar, and there are several other fields you may want to include when creating your Skuid model:

  • Start Date Time: The starting time for an event as a datetime field.
  • End Date Time: The ending time for an event as a datetime field.
  • Body Content: The full-length description of a calendar event.
    • This is a rich text field, meaning it can contain HTML that is also editable in Skuid.

As seen with the $top default condition, the event entity can also accept OData system queries as condition parameters.

The event entity’s startdate and enddate conditions can be set using a variety of strings:

Note

For number-based keywords (indicated by a capital N), append :<number> to define the number value.

For example, to create a value of “10 years ago,” use N_YEARS_AGO:10, which would cover the range: 1/1/2012 >= [date_field] < 1/1/2013). These keywords can only accept positive numbers.

  • NOW
  • YESTERDAY
  • TODAY
  • TOMORROW
  • LAST_90_DAYS
  • NEXT_90_DAYS
  • LAST_N_DAYS:<number>
  • NEXT_N_DAYS:<number>
  • N_DAYS_AGO:<Number>
  • LAST_WEEK
  • THIS_WEEK
  • NEXT_WEEK
  • LAST_N_WEEKS:<number>
  • NEXT_N_WEEKS:<number>
  • N_WEEKS_AGO:<number>
  • LAST_MONTH
  • THIS_MONTH
  • NEXT_MONTH
  • LAST_N_MONTHS:<number>
  • NEXT_N_MONTHS:<number>
  • N_MONTHS_AGO:<number>
  • LAST_QUARTER
  • THIS_QUARTER
  • NEXT_QUARTER
  • LAST_N_QUARTERS:<number>
  • NEXT_N_QUARTERS:<number>
  • N_QUARTERS_AGO:<number>
  • LAST_YEAR
  • THIS_YEAR
  • NEXT_YEAR
  • LAST_N_YEARS:<number>
  • NEXT_N_YEARS:<number>
  • N_YEARS_AGO:<number>

Note

Strings used to set a date or datetime value for future dates, such as NEXT_N_DAYS or NEXT_N_WEEKS, return a range of dates that match the query. Because these functions return a range of values—not a single value—only the first value will be used.

For example: If you set NEXT_N_DAYS to 5, it will return a range consisting of Next Day 1 - Day 5. Skuid will use the Day 1 value since it is the first value in that range.

Using Outlook tasks in Skuid

Because of its versatility, you can use the task entity in a variety of ways:

  • Display tasks and their relevant data in a standard Skuid table
  • Emulate Outlook functionality to select a task and view it’s details
  • Compare your tasks to your calendar events by using tasks as a Skuid calendar event source with the following properties:
    • Name Field: Subject
    • Start Field: Start Date Time
    • End Field: End Date Time

To utilize Outlook’s task organization features, you may also use the task folder and task group entities. In Outlook, tasks are contained within task folders, which are then contained within task groups.

Task Folder: This entity contains task folders, which serve as directories for individual tasks.

Fields

  • Id: (Default) The alphanumeric ID of a task folder. Within a Skuid page, use this value to set the taskfolder condition on tasks.
  • ParentGroupKey: (Default) The GUID key of a task folder’s parent task group. This field is different from the task group’s ID.

Conditions

  • groupid: Sets the task folder entity to query for tasks. Defaults to the end user’s primary task folder.

Task Group:

Fields

  • Id: (Default) The alphanumeric ID of a task group. Within a Skuid page, you’ll use this value to set the groupid condition on task folders.
  • GroupKey: (Default) The GUID key of a task group. This field is different from the task group’s ID.

Conditions

No conditions can be set for this entity.

Email

One of its most important features, Outlook mail is also accessible through the Outlook data source type. Through clever use of data source actions and Skuid app design, you can view, draft, and send messages—all through Skuid, using three entities:

  • Message
  • Mail folder
  • Drafts

By creating Skuid models for these entities (and using the data source actions associated with this data source type), you can use Outlook email in new, creative ways that fit your needs.

Message: A read-only entity that contains data for individual messages.

Fields

  • Id: (Default) The alphanumeric ID of a message.

Some additional fields to include within the message model:

  • Subject: The actual subject line of the message.
  • Body Content: A rich text field containing the contents of the message.
  • To Recipients: The intended addressee of the message.
  • CC recipients: A semicolon-separated listed of carbon copy recipients.
  • From Name - FromEmailAddress: The email address from whom the message was sent.
  • From Name - FromName: The name associated with the email’s sender.

Conditions

The following default conditions are available:

You may create additional conditions using other OData query options.

Using the Message entity

This field does not have any editable fields, and is primarily used with Skuid tables to display message data. However, by configuring a row action that runs the Message - Reply data source action, end users can reply to messages within their mail folders.

Mail folder: This entity contains mail folders, which serve as directories for different messages.

Standard mail folders include:

  • Drafts
  • Inbox
  • Outbox
  • Junk Email
  • Deleted Items
  • Conversation History

Fields

  • Id: (Default) The alphanumeric ID of a mail folder.

Some commonly used fields for this entity include:

  • Display Name: The descriptive display name for the mail folder.
  • Unread Item Count: The number of unread items within the mail folder.
  • Total Item Count: The total number of items within the mail folder.

Conditions

No conditions can be set for this entity.

Using the Mail Folder entity

Fields

  • Id: (Default) The alphanumeric ID of a draft.

Other fields commonly included in this model to facilitate draft editing are:

  • Subject: The actual subject line of the message
  • Body Content: A rich text field containing the contents of the message
  • To Recipients: The intended addressee of the message
  • CC recipients: A semicolon separate listed of carbon copy recipients

There are other fields available for even more detailed data.

Conditions

The following default conditions are available:

You may create additional conditions using other OData query options.

Using the Draft entity

If you’ll be composing and sending messages from your app, the draft entity provides a lot of that power within Skuid.

One use case is a Skuid table attached to a drafts model, with two configured row actions:

  • Edit Message: Opens a popup containing a field editor, which allows the end user to edit the draft’s fields,
  • Send Draft: Using the Draft - Send data source action, this row action sends the edited draft.

With this relatively simple configuration, you have functional email creation within Skuid.

Contacts & Contact Folders

Outlook contacts—commonly used in conjunction with Outlook email—allow end users to keep track of a wide range of data about their acquaintances in a virtual address book. These contacts are organized by contact folder. Skuid accesses this contact data through two entities: Contact and Contact Folder.

Contact

Fields

The Contact entity pulls the actual data for individual Outlook contacts. It has three default fields:

  • Id: The alphanumeric ID of a contact
  • GivenName: Contact’s first name.
  • Surname: Contact’s last name.

In addition to these fields, this model entity can access a wide variety of contact fields, such as business addresses, home addresses, company names, and so on. Select any of the fields needed for your use case.

Conditions

The following default conditions are available:

Note

You cannot use the Contact Folder name as the value in the contact model condition; you must use the Id field[ (see Fields, above). This can be obtained by creating a Skuid component that includes both the contact folder names and Id fields. When displayed in runtime, copy the ID that corresponds to the desired contact folder.

Contact Folder

Fields

The Contact Folder entity is used to access the full list of Outlook contact folders associated with an account. The IDs from these folders can then be used in thecontactFolderId condition of the Contact entity (see Contact, above)to limit which contacts are queried.

This entity has three default fields:

  • Id: Alphanumeric ID of a contact folder.
  • DisplayName: Name of the contact folder.
  • ParentFolderId: If the contact folder is a subfolder, the alphanumeric ID of the parent folder.

Conditions

The following default conditions are available:

  • $top: Determines how many records will be loaded into this model, “the top X number of records.” Related to the $top OData query option.By default, this is set to 200.
  • contactFolderId: The contact folder to query for contacts.

File Attachment

The File Attachment entity is used to pull in all attachments associated with one specific “container,” which can be either a message or a calendar event. Both of this entity’s conditions must be set to work properly, so it’s best practice to uncheck the Query on Page Load property.

Fields

  • Id: (Default) The Alphanumeric ID of a contact folder.

All additional fields correlate to the properties listed in Outlook’s file Attachment resource documentation.

Conditions

This entity has two default, required conditions: attachmentsOn and attachmentContainerId.

  • attachmentsOn: Set this condition to messages or events based on which entity should be queried for attachments.
  • attachmentContainerId: Set to a specific Id for either a message or an event.

Hardcoding a container Id leaves little room for user interaction with the model. Instead, it is best practice to allow users to set these conditions at runtime using Activate & Set value of Model Condition. Use actions that pass along context—such as row actions on a table—to enable end users to choose which container they wish to query.

If uploading an attachment results in an error, there are two main causes:

  1. The conditions on the File Attachment model may not be set properly. Double check these conditions and any actions affecting them.
  2. Your Azure app permissions may not match those needed for file attachments. Ensure the app registration has all permissions listed here.

As previous permission configurations can sometimes persist, you may need to create a new Azure app, reapply all the permissions, and update your authentication provider.

Data Source Actions

The Outlook data source type has features to facilitate email functionality within Skuid. Using thoughtful design and merge syntax, you can use these actions to create something resembling a full-featured email app—alongside any other Skuid page features you’re already using.

  • Download attachment: Used as a row action, this data source action will download the file attachment passed to it as context. If used without context—such as in the Button Set component—this action download the attachment specified in the first row of the model.

Note: If attachments do not download correctly, add the Content Bytes field to the File Attachment model.

  • Model of attachments: Select a File Attachment model that queries for a specific container’s attachments.
  • Draft - Send: When given a draft record as context, this data source action will send the draft to the specified recipient, and will then move the draft into the Sent Items mail folder.

    Note

    This action will not requery the draft table, so it is recommended that you pair this action with a Query Model action.

    Using this Draft- Send within row action on a Skuid table of email drafts gives it the proper context, i.e. a draft to send.

    • Model of Drafts: The model that contains the draft records to use for context.
  • Message - Reply: This data source action is functionally the same as Draft - Send, but is used to directly reply to an existing email chain—placing the message within that chain when it is sent.

    • Reply to:
      • All: Replies to all participants in the message thread.
      • Sender: Replies only to the sender of the message and not all listed participants.
    • Reply Content: The body of the email reply. This field accepts HTML and merge syntax.
      • Use this in conjunction with a UI-only field and field editor to give end users the ability to write full messages.
  • Send New Message: Use this action to generate an entirely new message—no drafts or message threads needed. Merge syntax can be used within each its content fields.

This works very well as a row action within a table. For example, placing this as a row action for a table of accounts would allow users to quickly send pre-written emails to those accounts, with the proper names filled in using merge syntax.

  • Subject: The subject line of the email being sent.
  • To: The recipient of the email. Multiple recipients can be specified by separating each email address with a semicolon.
  • BCC and CC: Semicolon separated lists of emails for blind carbon copies and carbon copies respectively.
  • Message Content: The body of the email being sent.
    • Use this in conjunction with a UI-only field and field editor to give end users the ability to write full messages.
  • Content Type:
    • Text: Specifies that the message content is strictly plaintext. If HTML is entered, it not be rendered
    • HTML: Specifies that the message content does contain HTML, and that it should be rendered.

The Apex Proxy

In Skuid SFX, the Outlook data source type will send data update requests and file uploads directly to Outlook—bypassing the Apex proxy—even if the Use Apex Proxy field is enabled. This due to the way the Apex proxy sends requests.

While this will typically have no impact on the use of Outlook in your Skuid SFX site, certain firewall settings may cause issues. If you notice that your Outlook data source isn’t performing as expected, talk to your IT administrator.

Troubleshooting

Common Errors [[]]

When configuring Microsoft data sources, several common errors may deal with authentication and data source configuration. If you receive errors when logging into the OAuth popup window, check the following:

  1. The authentication provider’s authorize endpoint URL contains your Office365 domain name.
  2. The client ID and client secret match the application ID and a key from your app registration
  3. Ensure that you are not logging into to another (different) Office365 account. Switching accounts will cause issues with cookies and not allow you to properly authenticate, especially if the accounts are in two separate Office365 domains.

There are several specific errors you may encounter:

  • Data source and app registration scopes have been updated, but the end user can’t access data from Skuid.

    The changes to permissions may have not had enough time to propagate in Microsoft’s servers. Try again later.

  • Error message: This application requires application permissions to another application.

    Additional messaging: Consent for application permissions can only be performed by an administrator. Sign out and sign in as an administrator or contact one of your organization’s administrators.

    There is an issue with your application registration permissions. Ensure you have set your permissions as Application Permissions instead of Delegation Permissions.

  • Error message: Could+not+find+the+authenticating+server,+https://login.microsoftonline.com/common/oauth2/token

    This error message indicates issues with your OAuth authentication flow.

    Try each of the following steps in turn:

    1. If logging in with multiple Office365 accounts, or using an account without the appropriate licenses, try clearing the cookies.
    2. Check that your client ID and client secret have been entered correctly in the authentication provider. If you’ve lost your client secret, create a new key in your Azure AD app registration and update the authentication provider.
    3. Delete the Skuid data source and recreate it, pointing to the same authentication provider.
    4. If all else fails, delete any and all existing data sources and authentication providers for the Microsoft service you’re configuring and then recreate them.

Using the Action Framework to query an Outlook model does not seem work [[]]

Outlook model queries can vary in time. Users should know that their queries may take up to twelve seconds.

Request to data source “OutlookAgain” failed; two error messages [[]]

The error messages:

Request to data source "OutlookAgain" failed: Mailbox is awaiting JIT provisioning

or

Request to data source "OutlookAgain" failed: Not Found: REST API is not yet supported for this mailbox.

  • If the end user receives these error message, they may not have a license for Outlook within your Microsoft organization settings. Determine if the Outlook tile is available at portal.office.com, and verify that the user has all required licenses with your IT administrator.
  • If an Outlook license has been granted recently, it may take some time to propagate in Microsoft’s servers. If the user has been granted a license, but still can’t access Outlook, they should retry later.

Request to data source “Microsoft-Outlook” failed: Server Error in ‘/API’ Application [[]]

Runtime Error Description: An application error occurred on the server...

  • You may not have set both conditions on the File Attachment entity model. Uncheck Query on Page Load and ensure that its two conditions have been set.