What is the Workspace¶
The Workspace is the environment where you do all your work in. It is the place where organizations and the assets that make up botlets get created and the permissions to them are managed.
What can you do in the Workspace¶
Developers use the Workplace to build conversational flows that integrate with outside services and work across channels. In fact, you do not need to do all the work by yourself. Most of the components are already created for you in the Store. Visit the Store and discover the components that interest you, and then bring them into your Workspace to try out in reuse. If you happen to not find any components that meet your needs, then you can use the Workspace to develop your own.
In the Workspace, you can do the following things:
- Compose a flow
- Create a component
- Define an action
- Assign read/write permissions to organizations and the assets that make up botlets
- Allow other people to view and modify your code
- Test to see how your botlets are behaving by using the chat tool
Ways to visit the Store and Workspace¶
There are three ways you can visit the Store:
Before you can begin a session in the Store portal and start using the Workspace, you must have a registered Microsoft Account (MSA). Access to the Store portal and the Workspace uses your MSA account credentials for authentication.
If you do not have a MSA and need to create one, click: Create One!.
If you encounter a technical issue and you require assistance, please send an e-mail message to:
What is the Store¶
The Store is simply a place for you to discover components published by other developers. The Store is also all about reuse. This means that you can add components in the Store that interest you, and have them brought over to your Workspace so that they can be reused in your own flows.
For more details about using the Store portal, see: Store Overview.
Exploring the Workspace User Interface¶
In this section, we are going to explore the basics of the Workspace user interface.
We will be exploring:
- The navigation ribbon
- How to search for items in the Workspace.
- How to log out of the Workspace
- How to find the developer token
- The location and descriptions of the Workspace window panes
Searching the Workspace¶
To search for items in the Workspace, click the magnifying glass in the Items Tree pane to expand the search field. You can also search the Workspace using parameters like a botlet ID or an entity ID.
Searching the Store versus searching the Workspace
When you search for items in the Store, the results that get returned are public items. Public items are items that are published to the rest of the world.
This compares differently to getting search results back in the Workspace. In the Workspace, you will see public items and your private items. Private items are organizations and their assets that have not been made public. Items that you create in the Workspace are private until you to publish them to the Store.
Logging out of the Workspace¶
- Click Settings on the navigation ribbon.
- Under Developer Properties, click Logout.
Finding the Developer Token¶
To find the developer token in the Workspace, click Settings on the navigation ribbon.
Under the Developer Properties section, you can view and copy the Developer Token. The Developer Token is a globally unique identifier (GUID) that is a 32-hexadecimal digit reference number used as an identifier to call other APIs.
Workspace Window Panes¶
As shown in the image below, the Workspace environment has three window panes where you do your work in.
The windows panes are called the:
- Items Tree
- Code Viewer
- Control Panel
Items Tree - Left-Side Window Pane
The left-side window pane is referred to as the Items Tree. The Items Tree has an icon that enables you to collapse and expand the window pane. The image below shows when the Items Tree is collapsed. When it is collapsed, you will not see displayed the Recent Items, Organization, and Store Items namespace directories. When the Items Tree is collapsed, you can click new to create a new organization and assets such as a botlet, service, entity, or renderer. Creating new an organization and assets are described in more details in the following sections of this document.
The image below shows when the Items Tree is expanded. It here that you can click to view components listed under the Recent Items, Organization, and Store Items namespaces.
The Recent Items folder contains all the assets that you had recently interacted with inside the Store and in the Workspace. The image below shows this folder expanded. To collapse any open folders displayed in the tree, click the Collapse all folder icon below the new button.
The Organization folder acts like a container for all the organizations that you’ve created in the Workspace along with any botlets, services, entities and renderers listed under them.
Note: Organizations and their assets can either be public or private. Private items are ones that have not been published to the outside world. Public items are ones that you’ve published to the outside world (i.e., Store).
The Store Items folder consists of items that you brought in from the Store. Inside the Store, there is a link called Add to my items. This link is located under all the botlets and services as shown in the image below.
When you click Add to my items, all the items that you select will get displayed inside the panel of the Store called My recent items. Likewise, these items will get added under the Store Items directory in the Workspace Items Tree such as Prebuilt Botlets. Prebuilt Botlets are botlets and assets created by Microsoft and other third-party developers. They encapsulate conversational flows that are frequently used by developers (e.g., getting a user’s location, or checking if a phone number is correct).
Note: Items that are inside the Store Items folder cannot be modified.
When the Store Items folder is expanded, there are 3 child folders, (i.e., samples, system, and mso. These samples, system, and mso folders are described in more details below.
The Samples folder consists of a repository of 10 tutorial botlets that you can try out and reuse the code in your own projects. Examining these sample botlets gives you the opportunity to interact with and to learn the details of the Semantic Composition Language (SCL).
For more details about SCL, see: Semantic Composition Language
The system folder consists of one service botlet for Language Understanding. It also consists of several entities. In addition, there are three categories of prebuilt botlets that you can reuse in your skills. These prebuilt botlets are contained inside the entity_resolver, interaction, and utility folders. The Microsoft Ontology (MSO) folder consists of MSO entity types. These folders are described in more details below.
The entity_resolver folder consists of the most widely used prebuilt botlets in our library. These prebuilt botlets can get a location, resolve a number, get the time, and more.
For more details about these prebuilt botlets and many more, see: Full List of Prebuilt Botlets.
The interaction folder consists of prebuilt botlets that are used in skills where users can talk and interact with digital assistants like Cortana. Some of these prebuilt botlets can take a user query and return a response like a selection of items. They can respond to a users verbal query and return a greeting response. These are just a few examples of what these prebuilt botlets can do in a skill.
The utility prebuilt botlets are a set of tools used in the backend of a skill. Examples of these tools include decoding html, encode or decoding a URL, get user location, paginate items, and get an airport code. These are just a few examples of what these prebuilt botlets can do in a skill. Utility prebuilt botlets use entity types that are unique to the get_city_around botlet. For more details about creating entity types, see: Entities. To see a list of entity type definitions, see: Entity Type Definitions.
The mso folder consists of Microsoft Ontology entities. It is recommended that you use MSO entities as input and output botlets. MSO is a set of entity definitions which describe many real-world objects.
Code Viewer - Center Window Pane
The center window pane is called the Code Viewer. The Code Viewer allows you to view and modify your code.
Control Panel - Right-Side Window Pane
The Control Panel gets positioned to different locations of the window panes depending on what is selected inside the Items Tree. The Control Panel enables you to edit and manage the properties of organizations, botlets, services, entities, and renderers with the use of menu tabs. The availability of the menu tabs will vary due to the selection of an organization, botlet service,entity, and renderer because they each have their own unique properties. Above the Control Panel, you can minimize and maximize the right panel. Expanding and contracting the right panel is helpful when you are reviewing and editing code.
This concludes this section on exploring the Workspace window panes.
In the next section, we are going to review the various menu tabs of the Control Panel. These menu tabs allow you to view and modify the properties of organizations and their assets.
Organizations - Parent Directory¶
When you click an organization parent directory in the Items Tree, it expands and displays a collection of individual organizations that are in your Workspace. Each individual organization acts like a container for the assets underneath it. These are the botlets, services, entities, and renderers. With an organization selected, it activates the Control Panel that has several menu tab options that allow you to view and make changes to the properties of organizations and the assets under them. These menu tabs are described in more details below.
The Overview menu tab is a summary of all the properties of the organization that is selected in the Items Tree. The properties that get displayed are the organization name, and the total number of botlets, services, entities and renderers under the parent directory. It also lists the number botlets and services published. In addition, it lists the number of child organizations created.
Granted Permissions Tab¶
The Granted Permissions menu tab allows you to see who are the designated administrators (admin) of the organization, and who are the developers that are members of the organization. You can promote a developer to the admin role, or you can change an admin to a developer role. You have the ability to designate additional admins to the same organization. You also have the options to add more developers or delete them when you need to. The admin is the only person who can add or delete people from the organization.
If you want to read more details about the concepts of permissions and how to grant them to Organizations and to developers, see: Permissions.
The Modules menu tab allows you to preview all the botlets and services created under an organization. You can search for them by their names. You can click their names inside the list. This will redirect you to the Overview tab of the component that you selected inside the Modules tab (i.e., botlets or services).
The Entities menu tab allows you to preview all the entities created under an organization. You can click on the name of entity in the list and be redirected to the Overview tab of the entity that was selected.
The organizations menu tab displays a list of sub organizations that have been added to a parent organization. Adding a sub organization to a parent organizations allows everyone in the parent organization to have access to the assets under the sub organization.
When you select a botlet in the Items Tree, several menu tabs get displayed inside the Control Panel. These menu tabs are described in more details below.
The Overview menu tab is the interface that allows you to inspect the properties of a botlet. It is the place where users with write permissions can modify a botlet’s description. You can also add new actions and add channels.
The Discoverability menu tab is the interface that allows you to enter a description of your botlet and add channel specific properties to it. This will ensure that it gets displayed in the search results across multiple channels, and it also helps with the discoverability of your botlet in the Store, Cortana, or in any other channel. You can also add tags that are custom key word values that help improve search results of your botlet.
Any botlet, service, or skill is searchable in the channel it is published to. If you want to control how your skill shows up in the Cortana search results, modify its properties like the description name. You may add extra keys words or tags. As an example, you have a flower ordering skill. To enhance its searchability in the Store, you may add tags in the discoverabiilty properties such as bouquet, florist, weddings, etc.
Note: If you publish a Cortana skill to production, the Discoverability menu tab will expand with more fields that will effect discoverability in various Cortana features.
For more system concept details, see: Discoverability.
The Publish menu tab is the interface used for publishing a skill to the outside world such as to a channel like Cortana. It is here that you can publish a skill to yourself, or you may publish a skill to a designated group of users that you choose.
For more details about the publishing process, see: Publishing.
Actions are the interfaces for botlets and services to allow them to be chained together and called. Actions take entity types as input and output parameters to ensure the semantic nature of the service. The Actions menu tab enables you to reuse existing entity types. It also allows you to create new entity types.
For more information on creating services and actions, see: Services.
Permissions is how we handle access management. The Permissions menu tab enables the administrator to control who has access to the botlets.
Organization permissions is like a tree where you can have assets underneath that tree. Every single developer who is on this organization will have access to all the assets that are under the organization.
Read / Write Permissions
Read / Write permissions are granted to organizations and individual developers using the corresponding tabs of the Permissions tab. All organization members by default have write permissions to all the assets under the organization. If a person has read only permissions, they can see the asset in the Store or get it via the API, but they cannot modify the code.
Execute permissions on an asset means that your botlet can be called by something else. You need this if the person can see the code, but still cannot run it from his own code because read/write and execute permissions are managed separately.
They can also be granted to an individual botlet or organization. People, entities, and renderers (i.e., assets) are not granted execute permissions. The reasons why people do not have execute permissions is that they can be members of multiple organizations.
For more information about the types of permissions and how to grant them, see: Permissions.
The Authentication menu tab is where you go to view, create, edit, or add OAuth2 configuration properties for botlets under an organization. OAuth2 is the only supported way of authentication of external services.
Under the Authentication tab, you can configure OAuth properties for:
As a best practice, consider what you want to do with your botlet when you are ready to publish it to the outside world. Do you want to publish it using your own OAuth2 authentication properties? Or do you want users accessing your botlet to use their own OAuth2 properties?
For more background information on authentication and how to apply OAuth configurations to a botlet, see: Authentication.
The Logs menu tab is the interface used for viewing log and error reports on skills. These logs are generated in the background while the skill is running. You can control the information that gets displayed in the logs by choosing various filter criteria such as Log Type (i.e., log, error, or all), Channel Type (i.e., Cortana, Bot Framework, etc.), Time Range, Session ID, and more. Logs are useful for troubleshooting issues with skills. They also allow you to monitor trends that occur in time such as number of successes and failures. The LOG SCL command sends log messages to the log console.
For more information on how to access log and error reports, see: Logs.
The Chat menu tab includes the Test Chat tool and the Test Cases panel. The Test Chat tool is a runtime channel used for executing a botlet’s functionality in the Workspace. This test tool enables developers to determine if the responses of a botlet are working properly. The Test Cases panel is the interface used for creating, running, editing and deleting test cases on a skill while it is being developed.
For more information on how to use the Test Chat tool and how to create test cases, see: Test Chat Tool.
The History menu tab is where you see modifications made to a botlet in a given point in time. It is here that you can run comparisons on the modifications made to a botlet by using the diff comparison feature. This presents a side by side comparison of the difference of the changes made to the code. You also have the option to revert any modifications made to a botlet.
For more information on about how to use the diff comparison feature, see: History.
When you select a service in the Items Tree, several menu tabs get displayed inside the Control Panel. These menu tabs are described in more detail below.
The Overview menu tab allows you to view the properties of the service botlet. It also enables users granted write permissions to edit the description of the service botlet, add new actions to it, and use the Copy to clipboard feature to copy the parameters of the action.
Discoverability properties help improve search results of services in the Store and in the Workspace. The Discoverability tab allows you to view, add, or modify the properties found inside the Overview page of a service botlet. You can change the primary and secondary categories, add or remove tags, and update its description. Tags are custom key word values that you add as properties to help improve search results.
The Services actions menu tab is used for setting the properties for an outside service that your botlet is exposed to. It is here that you can add new actions to your service. You can also edit and delete existing actions as needed.
Actions define the interfaces that allow people to come and execute your botlet. An action to a botlet is the chaining interface. If you want to make your service botlet consumable by any other botlet, you must have an interface to call your botlet. Therefore, it makes no sense to create a service that has no action to it.
For more details about service and action creation, see: Services.
The Permissions menu tab is where you go to grant read/write permissions to developers. It is also the place to grant organizations read/write/execute permissions.
For more details about the concepts of permissions and granting them to developers and organizations, see: Permissions.
When you select an entity in the Items Tree, four menu tabs get displayed inside the Control Panel. These menu tabs are described in more detail below.
The Overview menu tab allows you to view the properties of a botlet’s entities and see a list of the field names associated with the entities listed under the Organization.
Note: If you do not see any field properties listed in the Overview menu tab, it means that you’ve not created any fields for the entity that’ve you selected under an organization.
For more details about entity types, see: Entities.
The Fields menu tab is the interface that enables you to create, edit, and delete fields of an entity. It is here that you can define a field as an integer or a string. You can also include a description for the field and enable it with options such as required, senstive, and depricated 2.
The Discoverability menu tab allows you to add or modify the properties found inside the Overview page. You can change the entity’s primary and secondary categories, add or remove tags, upload an image for the botlet, and update its description. Tags are custom key word values that you add as properties to help improve search results.
The Permissions menu tab is where you go to grant permissions to developers and organizations. This enables how you can control access to the entities in your Organization. Developers and organizations can be granted read/write permissions to the entities under it.
The Renderers menu tab displays the name of the template, and it lists the channels selected for the renderer. You can click a link for the name of the template, and it will direct you to the renderer Overview menu tab.
When you select a renderer in the Items Tree, several menu tabs get displayed inside the Control Panel. These menu tabs are described in more detail below.
The Overview menu tab displays the renderer ID, and specifies the last date it had been modified. It lists the entity names associated with the renderer. You can also preview renderer templates from this tab too.
The Templates menu tab allows you to create or delete a template for a renderer under an Organization. You can view renderer’s properties to determine the channel, if it uses a single or list templet, the type of canvas and the image size of the HTML renderer card.
For more details about creating renderers and templates, see: Renderers + Templates.
The Permissions menu tab lists the developers and organizations that have permissions to the Renderer. Renderers are tightly coupled to entities. Permissions to renderers allow developers to read the HTML and CSS code. If they have write permissions to a renderer, they can modify the code.