Outlook

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

Using the OAuth credentials you created in Using Azure Active Directory with the OneDrive and Outlook Data Sources, complete the following two steps to use the Outlook data source type:

  1. Create the Outlook authentication provider.
  2. Create the Outlook data source.

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:

  4. Click Save.

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

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 App 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, 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 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:

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

Using Outlook calendars as a Skuid calendar event source

The event entity is used to supply events for display within the Skuid calendar. Once configured, it will function just like any other Skuid calendar, with full read/write capabilities.

  1. Drag and drop the calendar component into the canvas.

  2. Click Add Event Source.

  3. Click the newly created event source and set its basic properties:

    • Name Field: Subject
    • Start Field: Start Date Time
    • End Field: End Date Time
  4. Click the Event Display tab.

  5. Configure the event template using merge syntax:

    • To display the event title and description use {{Subject}} - {{bodyContent}}.

    Note: Because event descriptions can contain HTML, they may display unexpectedly within the calendar component.

Tasks

Providing intuitive and detailed reminders, tasks are another Outlook feature accessible using the Outlook data source type. You’ll primarily be working with the task entity.

Task:

This entity contains data on individual tasks.

Fields

  • Id: (Default) The alphanumeric ID of an individual task.

Similar to the event entity, the task entity contains the relevant details within several other fields:

  • Subject: The name of the task.
  • Body Content: A rich text field that contains a longer description of the task.
  • Due Date Time
  • Importance
  • Sensitivity
  • Start Date Time
  • Status

Conditions

The following default conditions are available:

You may create additional conditions using other OData query options.

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 using a queue and field editor 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 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 user 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, 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

One common use for the this model entity is creating a queue component that activates and sets the mailfolder condition within the message entity.

Draft: A read/write entity that contains data for all message drafts. Drafts can be created and edited within Skuid, and can be sent when used in conjunction with the Draft - Send data source action.

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 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 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 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 docs_url:context <skuid/glossary.html#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 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 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 on Salesforce, 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 on Salesforce 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.

Note

This does not affect Skuid Platform.

Troubleshooting

  • 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: 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 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.

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 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.
  • This application requires application permissions to another application. 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.
  • 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.