This document provides guidelines you can follow while developing new components and extending the existing EmpowerID functionality. These guidelines are about the naming conventions and tips that help you avoid known issues while developing components using the Workflow Studio.
The information provided is for the customers and their developer teams. These are merely prescriptions or suggestions which would make a good structure, and developers can establish their conventions or modify conventions prescribed here to suit their requirements.
General Tips
Always Create package folders in the Workflow Studio Source control. A project folder is a container that provides a logical structure for workflow applications and all associated components. Don’t use the stock packages folder of the EmpowerID product.
When altering a stock workflow, a best practice is to make a copy of the workflow and then modify the copied workflow. If the stock workflows are modified, future EID product upgrades might overwrite those workflows. Please consider following the naming conventions provided here in the section Naming Conventions.
Not just the workflow, while extending or altering any stock components, please create a copy, save it with a proper name following Naming Conventions and modify it.
Customizing and extending EmpowerID components requires inheriting and referencing stock libraries (Class, interface). Please find the instructions here Extend EmpowerID.
Naming Conventions
We work with various items while developing components in Workflow studio. A standard naming convention followed properly will help read, understand and maintain the code better. This section discusses how we can sensibly name the WFS items like Workflow, Form, and Properties within those items.
Placeholders: Please find the description of the placeholders used in explaining the naming conventions.
{CompanyInitial}- It can be the initials of your company, E.g., CI is an initial for imaginary company Circle International.
{Verb}- Verb is simply an action to perform, E.g., Create, Edit.
{TargetResourceType}- Resource the Action is being performed on, e.g., Person, Mailbox
{TargetResourceTypeAbbrevation} - Abbreviation for an EmpowerID object, for e.g. MR for Management Roles, BRL for Business Role Locations
Workflow Naming Conventions
This section discusses how you can name a workflow and its activities with examples of patterns you can use in certain situations.
Component | Pattern | Example | Description |
|---|---|---|---|
Workflow | {CompanyInitial}{Verb}{TargetResourceType} | CICreateMailbox, CIEditMailbox, CIDeletePerson, CIUpdatePerson | To name a workflow, start with the company initials and be preceded by the verb and target resource type. For the workflow called CICreateMailbox, CI is the company initial, Create is the Action, and Mailbox is the resource type. |
{CompanyInitial}{Verb}{TargetResourceType} | CIUpdatePerson | Some workflows execute multiple actions against the resource type, e.g., add and remove. To name such workflows with multiple actions start with the company initials and preceded by the Verb like update and target resource type. For the workflow CIUpdatePerson, CI is the company initial, update indicates the Action, and Mailbox is the resource type. Always choose a verb that makes sense of both actions. | |
{CompanyInitial}{Verb}{TargetResourceTypeAbbrevation} | CIDeleteMRMembership | Microsoft Windows allows only 255-260 characters for a file path. Shortening the name using abbreviations will overcome the limitation and increase the code readability. Some examples of abbreviations are MR for Management Roles, BRL for Business Roles, and Locations. To name such workflows with multiple actions, start with the company initials and preceded by the Verb and abbreviation of the target resource type. For CIUpdateMRMembership, CI is the company initial, and Delete is the Action Done against MR Membership. | |
{CompanyInitial}{Verb}{TargetResourceType1}{TargetResourceType2} | CIAddAccountToGroup, CIRemoveAccountFromGroup | To name a workflow executing Action against multiple objects, start with the company initials, preceded by the Verb and the name of both target resource types. For CIAddAccountToGroup, CI is the company initial, and Add is the Action Done against Management Role Membership. | |
Workflow > Workflow Activity | {CompanyInitial}{Verb}{TargetResourceType}Activity {CompanyInitial}{Verb}{TargetResourceTypeAbbrevation} | CIResetPasswordActivity CIUpdateMRActivity | To name an activity inside a workflow, start with company initials and be preceded by the Verb, target resource type, and the word Activity. At last, to denote it as a workflow activity. For CIResetPasswordActivity, CI is the company initial, and Reset is the Action Done against Password. You can also use a Verb-like update when the activity is performing multiple actions. |
Form and Controls
This section will discuss the patterns to name the Form and its controls like data source and Lookup.
Component | Pattern | Example | Description |
|---|---|---|---|
Form | {CompanyInitial}{Verb}{TargetResourceType}Form | CIEditPersonAddressform | To name a Form, start with the company initials and preceded by the verb and target resource type ending with the word Form. For the Form CIEditPersonAddressform, CI is the company initial, Edit is the Verb, and PersonAddress is the target resource type. |
Form > Data Source | {ObjectName}Datasource | CountryDatasource | To name a Data Source, start with the company initials and preceded by the verb and target resource type ending with the word Form. For the Form CIEditPersonAddressform, CI is the company initial, Edit is the Verb, and PersonAddress is the target resource type. |
Form > Lookup | {ObjectName}Lookup {ObjectName}SingleLookup {TargetResourceAbbrevation}SingleLookup {TargetResourceAbbrevation}MultiLookup | DisabledPersonsLookup MRSingleLookup BRLMultiLookup | To name a lookup, start with a meaningful object name and end with the word lookup at the end. For a lookup DisabledPersonLookup, the word Lookup indicates the control and is binding the persons who are disabled to login. You can use single/multiple words to indicate if it is a single or multiple dropdown. You can also use abbreviations like MR and BRL to keep the name short and workaround the ms-windows file path character limitation for a file path. Microsoft Windows allows only 255-260 characters for a file path. Shortening the name using abbreviations will overcome the limitation and increase the code readability. |
Class Libraries & Connectors
This section will discuss the patterns to name the connector and the class libraries.
Component | Pattern | Example | Description |
|---|---|---|---|
Class Library Project | {CompanyInitial}Connector | CIHRConnector | To name a class library, use a friendly name to describe the class library, preceded by the word connector at last. For CIHRConnector, CI stands for company initials, and HR connector indicates the connector to connect an HR system |
Connector | {ObjectName}Connector | connector | To name a Connector, use a friendly name to describe the connector and add the word connector at last. For connector, Hr describes the connector as being developed to connect to an HR system. |
Class Name | Follow any accepted naming convention consistently. |
Folder Structure
In Workflow Studio, the workflow applications and other objects you develop are classified as solution items and placed in folders you create on your local development machine. These folders are simply containers for holding and organizing the items you are developing and are represented as nodes in the Source Control tree. Each time you create a new workflow, activity, user interface element, or other objects, Workflow Studio prompts you for the folder in which the object should be placed. It then places that within a Source Control folder underneath the selected folder.
Source Control folders exist for each item type that can be created in Workflow Studio and encompass the following:
Source Control Folder | Folder Purpose |
|---|---|
Adaptive Auth Rules | Provides a location for organizing Adaptive Auth Rules you create in Workflow Studio. |
Alert Receivers | Provides a location for organizing Alert Receivers you create in Workflow Studio. |
APIs | Provides a location for organizing APIs you create in Workflow Studio. |
Azure Functions V1 | Provides a location for organizing Azure Functions V1 apps. |
Azure Functions V3 | Provides a location for organizing Azure Functions V3 apps. |
Azure Functions V5 | Provides a location for organizing Azure Functions V5 apps. |
Azure WebJobs v3 | Provides a location for organizing Azure Web Job V3 apps. |
Business Rules | Provides a location for organizing Business Rule apps. |
Class Libraries | Provides a location for organizing Class Library apps. |
Console Applications | Provides a location for organizing Console Apps. |
Microservice V3 | Provides a location for organizing Microservice V3 apps you create in Workflow Studio. |
Microservice V5 | Provides a location for organizing Microservice V5 apps you create in Workflow Studio. |
Microservices v6 | Provides a location for organizing Microservice V6 apps you create in Workflow Studio. |
OAuth Extensions | Provides a location for organizing OAuth Extensions you create in Workflow Studio. |
SAML Extensions | Provides a location for organizing SAML Extensions you create in Workflow Studio. |
SCIM Microservices V2 | Provides a location for organizing SCIM Microservices V2 apps you create in Workflow Studio. |
SCIM Microservices V5 | Provides a location for organizing SCIM Microservices V5 apps you create in Workflow Studio. |
STS Extensions | Provides a location for organizing STS Extensions you create in Workflow Studio. |
UMA Extensions | Provides a location for organizing UMA Extensions you create in Workflow Studio. |
User Interface > Forms | Provides a location for organizing Forms you create in Workflow Studio. |
User Interface > Lookup Controls | Provides a location for organizing Lookup Controls you create in Workflow Studio. |
User Interface > UI Pages | Provides a location for organizing UI Pages you create in Workflow Studio. |
User Interface > Adaptive Cards | Provides a location for Adaptive Cards you create in Workflow Studio. |
Workflows > Activities | Provides a location for organizing Workflow Activities you create in Workflow Studio. |
Workflows > Applications | Provides a location for organizing Workflow Applications you create in Workflow Studio. |
Workflows > Composites | Provides a location for organizing Composite Workflows you create in Workflow Studio. |
Workflow Rules | Provides a location for organizing Workflow Rules you create in Workflow Studio. |
Tracing
Developers can build a tracing system using the class provided by EmpowerID. The implementation of TdnfTrace class will log the information into the Windows event log. The TdnfTrace logger logs the information inside EventViewer → Application and Services Logs → EmpowerID.
Developers can creatively formulate the logging information as per requirement and better understand the errors. A sample code snippet of using the TdnfTrace class is provided below.
if (ex.Message.Contains("Timeout"))
TdnfTrace.Current.TraceData(TraceEventType.Warning, 9900, "Rbac refreshing resource role review compiled operation took too long refreshing but will resume: " + Environment.NewLine + ex.ToString());
else
TdnfTrace.Current.TraceData(TraceEventType.Error, 10000, "Rbac refreshing resource role review compiled operation: " + Environment.NewLine + ex.ToString());
Only use EventID greater than 9500 and lesser than 15000. The EID product uses numbers below 9500.