Across frontline industries, our conversations with customers about task management lead back to one foundational goal: To provide a single place to see all required work and monitor how it’s going. The Tasks app in Microsoft Teams is designed to be that place.
- The existing task publishing feature in the Tasks app provides an out-of-the-box experience to centrally define and distribute tasks at scale across locations. Everyone from your central offices to your frontline workers can view the required work in Tasks and track it to completion.
- Released earlier this year, the business scenario API opens up additional ways to bring all required work into the Tasks app. With these new API capabilities, you can create tasks in response to signals you’re monitoring or create tasks to represent items in other systems of record. For example, when your machine health monitoring system fires an alert reporting failure of a specific machine, you can automatically create a task for the employees at that location to follow up. Similarly, if a site inspection report is submitted with a noncompliant response, you can automatically create a follow-up remediation task for the employees at that location. In addition, if your org maintains a separate source of information on planned work, such as a maintenance calendar for devices and machines, you can use the business scenario API to make sure that pre-planned work is automatically reflected in Tasks and kept up to date across locations.
With these new capabilities of the business scenario API, it’s easier than ever to leverage the Tasks app as the single place for your organization to see and monitor required work for your frontline.
What’s the business scenario API and what’s the benefit of introducing a new concept?
We created the business scenario API specifically to enable frontline organizations to capture tasks for their frontline workforce from other signals and systems of record.
There are several ways in which the business scenario API makes development and maintenance of a task management solution easier:
- Easier task creation, in any Team. You can create a task in the right team by providing the ID of the Team where the task should be created. The first time you create a task in that Team, a dedicated Planner Plan will be created in that Team for your business scenario. Subsequent task creation automatically uses the existing Plan in the Team. This eliminates the need to manage the Plan or create and maintain a Team-to-Plan mapping.
- Fewer unexpected application interactions. An application can create a business scenario and use that business scenario to create a task in any Team. The application receives access to all tasks created via that business scenario, but not to any tasks created in other ways. An organization with multiple task management applications can use business scenarios to allow each application to create tasks in any Team without accessing other tasks in the Team it isn’t meant to access. This reduces the risk of applications unexpectedly performing operations on one another’s tasks with undesirable outcomes.
- Apply permissions centrally. Every business scenario supports central configuration, including the ability to configure task permissions. You can determine which fields can be edited and which actions can be taken by the users in your frontline workforce — and by other apps. These permissions will apply to all tasks created via your business scenario. For example, one of the most common needs is to prevent users or other apps from deleting the tasks. You can configure the task permissions to disallow deletion by users and other apps, ensuring your application can manage the task lifecycle from start to finish.
- Map to external object or signal. When creating a task using a business scenario, you’ll be able to stamp an external ID on the task. This is a great way to store a unique key or ID for the corresponding record in an external system (such as the ID of the scheduled maintenance entry on the central maintenance calendar) or to store an identifier for an incoming signal that results in a task (such as the event ID of a warning event fired by a system monitoring for machine failure). What’s more, you can later query for that task based on the external ID rather than needing to create and maintain a task-ID-to-external-ID mapping to get back to the right task.
- Act as an application, not a user. The business scenario API supports application permissions. In contrast to delegated user permissions, application permissions allow for task creation in any Team and will not require user credentials. An IT administrator can enable your application to use the business scenario API with application permissions.
- Notifications when your tasks are updated (coming later this year). You’ll soon be able to subscribe to receive a webhook notification any time a task created with your business scenario is updated. This means you can apply updates to external systems to reflect the latest status of the work (for example, updating the external maintenance calendar to reflect that the maintenance work has been completed) or kick off the next step in a larger workflow (such as kicking off a new site inspection once the original compliance violations are resolved).
Access Permissions and Security Benefits
As noted above, using a business scenario provides an application with scoped access—the ability to create a task in any Team while providing access only to tasks created via that business scenario. With increased focus on security and privacy, using a business scenario will make it easier for the IT administrators you work with to approve your solution for use in the organization. They’ll rest easier at night knowing that your application will only have access to the tasks created with the associated business scenario. Meanwhile, you’ll have full control to access, update, or delete the tasks created with your business scenario, so you can manage those tasks across their lifecycle.
And if there are specific cases where you have an application that requires full access to all Planner task data across your organization, that remains a possibility. You can work with your IT administrator to grant your application org-wide application permissions with existing Planner APIs. These broad, org-wide permissions may be appropriate for specific high-trust, low-risk solutions like custom reports on the tasks across all of your frontline locations.
What’s the best way to get started?
Microsoft Graph Explorer is a great way to try out API capabilities. We recommend starting by creating a new business scenario and then creating your first task in a team.
You can view the documentation for using business scenarios with Planner tasks at https://aka.ms/PlannerBusinessScenario to learn more. (The tasks created within a Team are powered by Microsoft Planner. This is why you will use the Planner business scenario API to create tasks for a frontline team, and these tasks will appear in the Tasks app in Microsoft Teams.)
You can also review our initial announcement blog post for more information.