The Self Serve Model allows you to write classes that auto generate UI components for your feature. The idea is to allow developers from other feature teams, who may not be familiar with writing UI, to develop and own UX components. This is accomplished by just writing simpler TypeScript classes for their features.
What this means for the feature team
Can concentrate just on the logic behind showing, hiding and disabling UI components
Need not worry about specifics of the UI language or UX requirements (Accessibility, Localization, Themes, etc.)
Can own the REST API calls made as part of the feature, which can change in the future
Quicker turn around time for development and bug fixes since they have deeper knowledge of the feature
What this means for the UI team
No need to ramp up on the intricacies of every feature which requires UI changes
Own only the framework and not every feature, giving more bandwidth to prioritize inhouse features as well
Localization/en/<FEATURE_NAME>.json Please place your files only under "Localization/en" folder. If not, the UI strings will not be picked up by the framework.
This is a JSON file where the values are the strings that needs to be displayed in the UI. These strings are referenced using their corresponding unique keys.
For example, If your class file defines properties as follows
This file contains the definitions of all the data models to be used in your Class file and RP file.
For example, if your RP call takes/returns the stringProperty and booleanProperty of your SelfServe class, then you can define an interface in your FeatureName.types.ts file like this.
The RP file will host the REST calls needed for the initialize, save and refresh functions. This decouples the view and the model of the feature.
To make the ARM call, we need some information about the Azure Cosmos DB databaseAccount - the subscription id, resource group name and database account name. These are readily available through the userContext object, exposed through
userContext.subscriptionId
userContext.resourceGroup
userContext.databaseAccount.name
You can use the armRequestWithoutPolling function to make the ARM api call.
Your FeatureName.rp.ts file can look like the following.
Once the SelfServeType has been updated, update SelfServe.tsx for your feature. This ensures that the framework picks up your SelfServe Class.
constgetDescriptor = async (selfServeType: SelfServeType): Promise<SelfServeDescriptor> => {switch (selfServeType) {caseSelfServeType.example: { .... } ... ... ...// Add this for your new featurecaseSelfServeType.featureName: {// The 'webpackChunkName' is used during debugging, to identify if the correct class has been loadedconstFeatureName = awaitimport(/* webpackChunkName: "FeatureName" */"./FeatureName/FeatureName");constfeatureName = newFeatureName.default();awaitloadTranslations(featureName.constructor.name);returnfeatureName.toSelfServeDescriptor(); } ... ...default:returnundefined; }};
You can enable portal notifications for your feature by passing in the required strings as part of the portalNotification property of the onSaveResult.
Add the query string feature.showSelfServeExample=true&feature.selfServeSource=https://localhost:1234/selfServe.html?selfServeType%3D<SELF_SERVE_TYPE>
Click on the Self Serve Example menu item on the left panel.
For example, if you want to open up the the UI of a class with the type sqlx, then visit https://ms.portal.azure.com/?feature.showSelfServeExample=true&feature.selfServeSource=https://localhost:1234/selfServe.html?selfServeType%3Dsqlx
Self Serve Model
The Self Serve Model allows you to write classes that auto generate UI components for your feature. The idea is to allow developers from other feature teams, who may not be familiar with writing UI, to develop and own UX components. This is accomplished by just writing simpler TypeScript classes for their features.
What this means for the feature team
What this means for the UI team
Getting Started
Clone the cosmos-explorer repo and run
npm install
npm run build
Click here for more info on setting up the cosmos-explorer repo.
Code Changes
Code changes need to be made only in the following files
1. JSON file for UI strings
Naming Convention
Localization/en/<FEATURE_NAME>.json
Please place your files only under "Localization/en" folder. If not, the UI strings will not be picked up by the framework.
Example
SelfServeExample.json
Description
This is a JSON file where the values are the strings that needs to be displayed in the UI. These strings are referenced using their corresponding unique keys.
For example, If your class file defines properties as follows
Then the content of
Localization/en/FeatureName.json
should beYou can learn more on how to define the class file here.
2. Types file
Naming Convention
<FEATURE_NAME>.types.ts
Example
SelfServeExample.types.ts
Description
This file contains the definitions of all the data models to be used in your Class file and RP file.
For example, if your RP call takes/returns the
stringProperty
andbooleanProperty
of your SelfServe class, then you can define an interface in yourFeatureName.types.ts
file like this.3. RP file
Naming Convention
<FEATURE_NAME>.rp.ts
Example
SelfServeExample.rp.ts
Description
The RP file will host the REST calls needed for the initialize, save and refresh functions. This decouples the view and the model of the feature.
To make the ARM call, we need some information about the Azure Cosmos DB databaseAccount - the subscription id, resource group name and database account name. These are readily available through the
userContext
object, exposed throughuserContext.subscriptionId
userContext.resourceGroup
userContext.databaseAccount.name
You can use the
armRequestWithoutPolling
function to make the ARM api call.Your
FeatureName.rp.ts
file can look like the following.4. Class file
Naming Convention
<FEATURE_NAME>.tsx
Example
SelfServeExample.tsx
Description
This file will contain the actual code that is translated into the UI component by the Self Serve framework.
Each Self Serve class
For every UI element needed, add a property to the Self Serve class. Each of these properties
Your
FeatureName.tsx
file will look like the following.5. Update SelfServeType
Once you have written your Self Serve Class, add a corresponding type to SelfServeType
6. Update SelfServe.tsx (landing page)
Once the SelfServeType has been updated, update SelfServe.tsx for your feature. This ensures that the framework picks up your SelfServe Class.
Telemetry
You can add telemetry for your feature using the functions in SelfServeTelemetryProcessor
For example, in your SelfServe class, you can call the trace method in your
onSave
function.Portal Notifications
You can enable portal notifications for your feature by passing in the required strings as part of the portalNotification property of the onSaveResult.
Execution
Watch mode
Run
npm start
to start the development server and automatically rebuild on changesLocal Development
Ensure that you have made the Code changes.
https://ms.portal.azure.com/
feature.showSelfServeExample=true&feature.selfServeSource=https://localhost:1234/selfServe.html?selfServeType%3D<SELF_SERVE_TYPE>
Self Serve Example
menu item on the left panel.For example, if you want to open up the the UI of a class with the type
sqlx
, then visithttps://ms.portal.azure.com/?feature.showSelfServeExample=true&feature.selfServeSource=https://localhost:1234/selfServe.html?selfServeType%3Dsqlx