UNIFIED WORKFORCE SDK
Bryan Jackson SLALOM CONSULTING 1500 Rosecrans Ave #410 Manhattan Beach, CA 90266 [Type text]
1
2
3
4
5
6
Introduction .......................................................................................................................................... 4 1.1
About Unified Workforce .............................................................................................................. 4
1.2
High Level System Diagram ......................................................................................................... 11
1.3
Full Module List ........................................................................................................................... 12
About This SDK .................................................................................................................................... 13 2.1
SDK Source Location ................................................................................................................... 13
2.2
Sample L4 Application ................................................................................................................. 14
2.3
Sample Tile with Live Feed .......................................................................................................... 14
2.4
Code Samples .............................................................................................................................. 15
2.5
Deployment................................................................................................................................. 15
Source Control .................................................................................................................................... 16 3.1
Getting connected ...................................................................................................................... 16
3.2
Branch Structure ......................................................................................................................... 16
Setting up Local Environment ............................................................................................................. 18 4.1
Visual Studio................................................................................................................................ 18
4.2
Certificates .................................................................................................................................. 18
4.3
Databases .................................................................................................................................... 19
4.4
Solutions...................................................................................................................................... 19
4.5
Libraries....................................................................................................................................... 19
UI Templates ....................................................................................................................................... 20 5.1
About UI Templates .................................................................................................................... 20
5.1
UI Template Project Location...................................................................................................... 20
5.2
Layouts ........................................................................................................................................ 20
5.3
Javascript..................................................................................................................................... 20
5.4
CSS ............................................................................................................................................... 21
5.5
Images ......................................................................................................................................... 22
Service Agents ..................................................................................................................................... 23 6.1
About service agents................................................................................................................... 23
6.2
Configuring live feeds.................................................................................................................. 24
6.3
Adding Feed to a Tile................................................................................................................... 26
6.4
Adding Tile to a screen ................................................................................................................ 28
6.5 7
Creating a new Service Agent ..................................................................................................... 29
Social Standing (Point Engine) ............................................................................................................ 34 7.1
About Social Standing ................................................................................................................. 34
7.1
Defining rules .............................................................................................................................. 35
7.2
Event Input Service ..................................................................................................................... 36
7.3
Scoring Output Service................................................................................................................ 37
7.4
Code Example.............................................................................................................................. 38
7.5
Extraction Agent.......................................................................................................................... 39
8
Work Order Management (WOM)...................................................................................................... 44 8.1
About Work Order Management ................................................................................................ 44
8.2
The WOMProxy ........................................................................................................................... 45
8.3
WOMProxyAgent & WOMProxyClient ........................................................................................ 45
8.4
Creating a WOM Proxy Agent ..................................................................................................... 48
8.5
Configuration .............................................................................................................................. 51
9
Level 4 Application Single Sign on ....................................................................................................... 54 9.1
About the authentication model ................................................................................................ 54
9.2
Setting up azure active directory access control ........................................................................ 55
9.3
Setting up your application for authentication........................................................................... 56
9.4
Securing controllers and controller methods ............................................................................. 59
9.5
Adding Federation Configuration to global.asax ........................................................................ 60
9.6
Adding the UserInfo class for simplified access to the current Identity ..................................... 61
9.7
Creating a login page for testing ................................................................................................. 62
10
External Application Single Sign on ................................................................................................. 63
10.1
About External Applications........................................................................................................ 63
10.2
Syncing in Admin Portal .............................................................................................................. 63
10.3
Live Tile Configuration ................................................................................................................ 64
10.4
External Website SSO Support .................................................................................................... 64
10.5
Creating a Service Agent ............................................................................................................. 65
10.6
Adding a Service Agent to Admin Portal ..................................................................................... 65
11
Deployments ................................................................................................................................... 67
11.1
Merge to Main and Label ............................................................................................................ 67
11.2
Deployment Documents ............................................................................................................. 68
11.3
Editing Build Configuration ......................................................................................................... 69
11.4
Archive Existing Deployments ..................................................................................................... 70
11.5
Deleting Existing Deployments ................................................................................................... 70
11.6
Delete Service Bus Queue ........................................................................................................... 71
11.7
Cleaning temporary databases ................................................................................................... 71
11.8
Ensure Correct Certificates ......................................................................................................... 71
11.9
Automated Build Scripts ............................................................................................................. 72
11.10
Manual upload if deploy fails .................................................................................................. 74
11.11
Swap Staging Instances ........................................................................................................... 75
12
Validating Performance .................................................................................................................. 77
12.1
How to Profile ............................................................................................................................. 77
12.2
Analyze the results ...................................................................................................................... 80
1 Introduction 1.1 About Unified Workforce Unified Workforce (UW) is a modular platform that centralizes access to information workforce employees need to do their job such as training, work orders and purchase orders. The system consists of Windows 8 style applications that have a tile-layout view and is customizable based on the user’s role. The main application, Metro Wrapper, links out to internal and external applications through single sign on providing a seamless experience to users. Actions taken inside of UW can reward (or take away) points providing an incentive to users of the system to participate. Much of UW was designed to be maintained through an Admin Portal. All of these components are designed to be run on Microsoft’s Azure cloud platform. UW has been designed with four primary different levels of screens (1 through 4). Throughout levels 2 through 4, charm and jump bars provide access to global and level specific actions. These screens are defined through the Admin Portal.
1.1.1 Level 1 – Login Page
1.1.2 Level 2 – Metro Wrapper – My Rhythm The My Rhythm screen is a unique Level 2 screen that utilizes Google Analytics history for the user and a weight value assigned to the Tiles to show the most important and most frequently used items.
Charm bars are accessable at any time by clicking the black tab on the right hand side of the screen and provide navigational and application level functionality depending on the level of screen.
For more information on Tiles, Screens, and Charms see the Service Agent section of this SDK.
Notifications, points, and jump bar is visible in the top-right corner of the screen.
The Jump bar provides navigation to visited UW Components, the home screen, user settings, help, and the log out.
1.1.3 Level 2 – Metro Wrapper – My Role, My Experience Additional tabs can be defined at Level 2 through that Admin Portal. Currently, these tabs are My Role and My Experience. My Role consists of application tiles that are closely related to the role of the signed in user. My Experience will be a feature added in a future version of UW.
1.1.4 Level 3 – Metro Wrapper - Application Tiles Selecting a tile at Level 2 will take you to an Application focused level 3 screen with two tabs, Ready and Related. The Ready tab consists of tiles specific to the application and includes Live feeds. Selecting a Live tile will bring up the detail of the data as well as the option to launch the external application if applicable.
The Related tab consists of links to related external applications.
1.1.5 Level 3.x – Metro Wrapper – Tile Detail Selecting a tile will bring up the detail for that tile. This detail includes the fields that were configured to display from the Live feed as well as a link to Launch the application
1.1.6 Level 4 – Internal Applications (SSO) Applications that have been created for the Unified Workforce platform are considered Level 4 screens. These screens feature fully functional applications with their own unique functionality. These modules are hosted completely independently of the Metro Wrapper but use SSO to provide seamless authentication. The look and feel of these applications are kept consistent through provided UI Templates.
1.2 High Level System Diagram Unified Workforce has been designed with a modular architecture. Each module is hosted in it’s own Azure instance(s) and communicates through a central communications service. As much as possible, the system has been designed to be configured through an Administration Portal.
1.3 Full Module List Metro Wrapper
Message Processor
Communication Service Admin Portal Social Compulsion
Contextual Learning Learning Engine eService Social Dispatch
Social Standing
Contains level 1 through 3 screens. Level 1 screen provides login through Azure AD Services. Level 2-3 provide a tile layout with a summary of information from each application as well as global navigation components. Provides a modularized wrapper for accessing the communication service. The metro wrapper’s tiles and notifications are fed through the message processor. Hosts all of the individual service agents which are responsible for communicating with external web services and databases. The configuration interface for Unified Workforce where Users and Application configurations are managed. This application provides a field worker view of work orders assigned to them allow them to check them in/out. It has also been designed to work offline in the event of a loss of connectivity. A repository of videos that can be accessed on demand for learning on any topics a user is interested in. Provides a workflow driven series of learning exercises to direct users through training modules. Provides an office-worker view of work orders and technicians. Also referred to as the Hopper. Takes work order items from all integrated work order (WOM) systems and distributes them to users so they can be picked up to be worked. Provides an engine for rewarding and taking away points for users interactions with Unified Workforce. These points can be used by other applications to further reward users for participation.
2 About This SDK This SDK has been written to provide a high level overview of UW and its components and provide code examples that utilize the systems core components. Source code examples are available for the following:
Level 4 application UI Templates Level 4 application SSO Service Agent WOM Agent Example Code WOM Service Interface Examples Social Standing Integration
Documentation is available for all of these code examples plus the following:
External application SSO TFS Guidance Local Environment Setup Deployment Process
2.1 SDK Source Location This document and all code examples can be found in source control under: $/ABMUW/Slalom/Source/SDK
2.2 Sample L4 Application A Sample L4 application has been provided as part of this deployment. This application is a simple one page application that lets a user add a Contact while demonstrating samples of SSO, UI Templates, Social Standing integration.
2.3 Sample Tile with Live Feed A sample tile has been created in the Integrated environment that has a Live Feed to contacts added. The Tile also includes a link to the Sample L4 Application which demonstrates SSO.
2.4 Code Samples In addition to the L4 application, code samples are available for the WOM System for both integrating with the WOM Service as well as skeleton code for creating a new WOM Integration.
2.5 Deployment Configuration has been provided for deployment into the Integrated environment. Right-click on the ABM.SDK.L4.Cloud project and publish it. Selected the SlalomSDKL4Test profile.
The application will build and publish to the environment.
3 Source Control Prerequisites: TFS, Branching/Merging, Visual Studio. Unified Workforce is stored on a cloud hosted TFS server. Bugs and work items are tracked here. Source control resides in Main and development branches. Each partner has their own development branch(s). Branches should be merged to Main when ready for a release.
3.1 Getting connected Server: unifiedworkforce.visualstudio.com Credentials: Provide a windows live account username to ABMs TFS administrator to be given access then login with this user. Team Project: ABMUW
3.2 Branch Structure Unified Workforce follows a main branching structure where development branches are created off of a Main branch and changes are merged to main prior to release to production. Each partner has their own branch and integrate with each other by merging to Main.
4 Setting up Local Environment Prerequisites: Visual Studio, TFS, Certificates, Azure Emulators, Azure Deployments, SQL, SQL Azure, Web.config transformations.
4.1 Visual Studio Visual Studio 2012 and 2013 are both compatible with Unified Workforce, however as of this writing UW requires an upgrade to v 2.2 of the Azure SDK to compile in 2013. The Azure SDK is a required add on that must be installed for whichever version of Visual Studio you are using and can be found here: http://www.windowsazure.com/en-us/downloads/ Previous versions of the SDK can be found here: http://azure.microsoft.com/en-us/downloads/archive-net-downloads/
4.2 Certificates Certificates are used by WCF services and Azure AD for authentication. WCF services require the key to be installed in the Trusted People store of local machine in order for PeerTrust based certificate validation to function. The certificate can be found here: $/ABMUW/Documents/Certificates/ABM/UW2013 - Update Peer trust store:
It is important to keep the correct certificates up to date when they change or deployments will fail.
4.3 Databases 4.3.1 Admin Database The Admin database is required for almost all UW components. It can be deployed locally or into an Azure environment. A copy can be taken from the Integrated environment as no from-scratch deployment scripts exist.
4.3.2 Application Specific Databases Application Social Standing Contextual Learning Social Compulsion
Source Location $/ABMUW/Main/Source/ABM.UW.SocialStanding/Data/Database $/ABMUW/Main/Source/ABM.UW.ContextualLearning/Data/Database $/ABMUW/Main/Source/ABM.SC/DB
4.4 Solutions Application Metro Wrapper Communication Admin Portal Social Standing Social Compulsion Social Dispatch Contextual Learning eService Learning Engine
Source Location $/ABMUW/Main/Source/ABM.UW.sln $/ABMUW/Main/Source/ABM.UW.Communication.sln $/ABMUW/Main/Source/ABM.Admin/AdminPortal.sln $/ABMUW/Main/Source/ABM.UW.SocialStanding.sln $/ABMUW/Main/Source/ABM.SC/ABM.SC.sln $/ABMUW/Main/Source/ABM.UW.SocialDispatch.sln $/ABMUW/Main/Source/ABM.UW.ContextualLearning.sln $/ABMUW/Main/Source/ABM.UW.EService.sln $/ABMUW/Main/Source/ABM.UW.LearningEngine.sln
4.5 Libraries 3rd party libraries that are not installed from NuGet and core compiled UW libraries are stored in source control one level above the source folders. They can be found here: $/ABMUW/Main/Libs
5 UI Templates 5.1 About UI Templates Prerequisites: Admin Database, CSS, Javascript, .Less, Handlebars. UI Templates is a solution that contains layout, css, image, and javascript files used inside of UW. To keep the look and feel of all internal UW applications consistent these template files should be copied into all Level 4 applications. As of this writing, UW 2013 UI Templates do not have any data access code to drive populating the charm and jump bars and this must be wired up manually be each application. UW 2014 will include the data access code so this manual wire up will not be required.
5.1 UI Template Project Location Files need to be copied into the level 4 applications from the UI Templates Project. They can be found here: $/ABMUW/Main/Source/ABM.UW.UITemplates
5.2 Layouts Layouts provide the basic HTML shell for the layout and individual components.
_Layout.cshtml provides the main layout for the application. It includes:
References to the _Header, _CharmBar, _SearchPane, and _SettingPane layouts. References to libraries, framework, uicomponents,customs, and demo scripts. Styles.less
5.3 Javascript The UI Template components depend on the handlebars and jquery libraries. The Framework javascript library consists of the base javascript all UI components use.
The UIComponenets library consists of the javascript for each of the common UI componenets.
5.4 CSS CSS has been defined using the .less css module which will need to be installed in your application. .less files exist for Variables, Mixins, Base, Layout, and Modules. The main style file that should be referenced is Styles.less.
5.5 Images Common images can be used in your application. These have been supplied in the Images folder.
6 Service Agents 6.1 About service agents Prerequisites: Admin Portal, UW Communication Service, WCF. Service agents are the live feeds for Unified Workforce that are used to push data to tiles. The service agents are hosted inside of the Communication Service application (Agents.Service) and are accessed through the MessageService. Service Agents in turn access other third party or internal services and databases, map the data to/from that service, and return it back to the tile via the MessageService. The MessageService determines which items are new since the last time the individual user viewed that live tile using a configurable date column.
6.2 Configuring live feeds The agents are configured into live feeds in the admin portal. Live Feeds are found under User Interface > Live Functionality
After selecting a service agent, you must select the Functionality (the internal methods of the service agent) and the parameters you want to pass. The column that contains the create/modify date is defined in the “Update Date Element Name”. This column drives which rows of data are qualified as new to the user viewing the tile. Friendly messages can be defined for errors or when no new data is available. Columns of data that returned and what order they are displayed can be defined Extra parameters can be defined that allow for fixed or dynamic parameters from user’s session data to be passed. The following dynamic parameter values are currently available for the user’s session: {HashedUserId} {HashedUserIdForLms} {IndustriesCollection} {OfficeCollection}
{OrgCollection} {ServicesCollection} {SiteCollection} {UserEmail} {UserId} {UserOrgCode} {UwTechId} {ZipCodeCollection}
6.3 Adding Feed to a Tile Tiles are used to contain the live feed results and can be configured under the Admin Portal User Interface > Tile section. All aspects of a tiles visual state can be configured as well as the action that occurs when a tile is clicked. Live Feeds appear as selectable under “Available Content� and up to 3 Live Feeds can be added.
To get the count of records returned to show in the tile, the Live Content section needs to be filled out with a palace holder in brackets for the numerical value.
6.4 Adding Tile to a screen Screens can be configured at different levels and contain Tiles. They are found under the Admin Portal User Interface > Screen section. Tiles can be added to screens and will appear on that screen on the next load.
6.5 Creating a new Service Agent 6.5.1 Implementing IAgent The service agent should be created as a class library and references should be added to the core UW libraries found here: $/ABMUW/Main/Libs/UnifiedWorkforce 1. Create a class that implements the IAgent interface (Configure and Process methods). 2. In the process function you will have your implementation of connecting to the external web service or database repository. 3. If the agent is being accessed through the MessageProcessorBridge, the results should be a List of GenericEntity or inherit from GenericEntity as the MessageProcessorBridge is expecting entities to be of that type. 4. Results should be transformed to XML XElement classes and returned back in the ResponseInfo class MessageBody. public ResponseInfo Process(RequestInfo requestInfo) { ResponseInfo result = null; var functionParameters = new Dictionary<string, string>(); if (null == requestInfo || null == requestInfo.TargetService || string.IsNullOrWhiteSpace(requestInfo.TargetService.OperationName)) { throw new InvalidDataException("requestinfo"); } var operationName = requestInfo.TargetService.OperationName; UriBuilder uriBuilder = new UriBuilder(requestInfo.TargetService.ContractName + "/" + operationName); WebClient client = new WebClient(); var resultString =
client.DownloadString(uriBuilder.ToString());
var contacts = JsonConvert.DeserializeObject<List<ABM.SDK.L4.Entities.Contact>>(resultString); var genericResults = contacts.Select(c => new GenericEntity() {Createddate=c.DateCreated,Name=c.FirstName,Id=c.ContactId.ToString(),Value="1",Description=c.FirstName,Createdby="1" }).ToList(); var xmlContacts = Serialize<List<GenericEntity>>(genericResults); result = new ResponseInfo { ResponseMessage = new MessageInfo { MessageBody = XElement.Parse(xmlContacts) } }; return result; }
6.5.2 Adding to Admin database After creating your service agent, you will have to add it into the admin database table ServiceAgent and each individual function you have into the [Function] table. It is recommended to store the web service endpoint configuration in the [Function] table’s ContractName field. This configuration will be passed through into your Service Agent.
6.5.3 Adding to Web.Config The communication service loads the assemblies at run time by reading the entries in the web config. Your service agent assembly must be configured in the Agents.Service project’s web.config in order to be found. The name field must match what is configured in the Admin database. The assembly must be signed so that it is strong named. <add name="SDKAgent" type="ABM.UW.Communication.Agents.SDK.SDKAgent" assembly="ABM.UW.Communication.Agents.SDK, Version=1.0.0.0, Culture=neutral, PublicKeyToken=398904be6bbe4b10" />
An Agent Mapping must also be setup in the web.config. <abm.uw.agentMappings> <!-- Case sensitive --> <reference name="MXWOSPQUERY"/> <reference name="MaximoMXSiteQuery"/> <reference name="Location"/> <reference name="Metropolis"/> <reference name="SocialCompulsionAgent"/> <reference name="RestAgent"/> <reference name="Storage"/> <reference name="SocialDispatchAgent"/> <reference name="VenuServiceAgent"/> <reference name="WOMProxyAgent"/> <reference name="LocalLaborAgent"/> <reference name="SDKAgent"/> </abm.uw.agentMappings>
6.5.4 Deploying Your agent assembly must be deployed to the CommunicationService. The Agents.Service project must contain a reference to your project either through a reference to the Libs folder or a project reference if it’s contained within the Communication solution itself.
The cloud service Communication.HostedService can then be deployed locally or to Azure.
6.5.5 Sample Code & Source Locations The Communication Service can be found under source control:
The SDK samples can be found under source control here:
Sample code for a service agent is found under the SDK Solution in the Agents.SDKAgent project
7 Social Standing (Point Engine) 7.1 About Social Standing Prerequisites: Admin Portal, ABMLQ (Word Press), WCF, Azure Worker Roles, IoC (Inversion of Control), Entity Framework. Social Standing is a point engine that allows different events inside of Unified Workforce to award or remove points to users of the system for taking actions. For example, completing a work order on time rewards points and leaving a work order open too long takes away points. These points are displayed inside of UW in the header in addition to the chalice for having the highest score.
Rules are defined in the admin database and define how many points to award for each event. At a high level, the system consists of: Event Input Service Event Output Service Event Processor Worker
Extraction Agent Worker Labor Ranking Worker
Web service endpoint where new events are fed into the system. Web service endpoint where the current users score can be retrieved. Worker that processes the raw event data, applys the business rules, and updates the users point score. Worker used to process abmlq and import the points from that system into Unified Workforce. Worker used to update the labor specific score to be used to social dispatch (hopper) when prioritizing where to route work orders.
7.1 Defining rules Rules are used to give or take away points for actions taken by users inside of Unified Workforce. Rules can be configured in the admin under Internal Application > Social Standing > Rule Set. Rules are contained within Rule Sets. Rule Sets define the component and organization level to apply the rule.
Rule Sets contains Rules. Rules define different events that can be triggered and the number of points to award for the event. A date range can also be provided to expire a rule at a specific time. Filters can be applied to the event data to limit the score. Points can be awarded as a percentage or as a fixed number of points.
New Event Types can be added under Internal Application > Social Standing > Event Types. For consistency, the name of the Event Type should be prefixed with the applicable module name followed by the action taken (e.x. ContextualLearning.Media.Approve).
7.2 Event Input Service The event input service is used to feed triggered events into the points engine. It places the incoming events into temporary storage after enriching it with additional data from the social standing database for later processing.
https://abmuwsocstandint.cloudapp.net/eventinput The web service expects an API Key and must be provided as an EventInputAPIKey header value. The EventInput web service receives an EventInputRequest through an HTTPPost. [HttpPost] public EventInputResult SubmitEvent([FromBody]EventInputRequest request) public sealed class EventInputRequest { /// <summary> /// Gets a unique identifier for the request created by the system that is the source of the event. /// </summary> /// <remarks> /// This will be used to check for duplicate messages that may be received due to transmission or other network issues. /// </remarks> public Guid SubmitterEventID { get { return this._submitterEventID; } } /// <summary> /// Gets a collection of entity keys that signifies for which entities the event is being submitted. /// At least one target entity must be submitted. /// </summary> public IEnumerable<EntityKey> Entities { get { return this._entities; } } /// <summary> /// Gets type of the event being submitted. /// </summary> public string EventType { get { return this._eventType; } } /// <summary> /// Gets the date and time at which the event actually occurred. /// </summary> /// <remarks> /// Due to delays in processing or network issues, this time may be in the past, although frequently it will be very close to the time at which the event is actually received by the service. /// If the EventTime value contains no time zone information, it will be assumed to be in UTC. /// </remarks> public Nullable<DateTime> EventTime { get { return this._eventTime; } } /// <summary> /// Gets extended event data as an IDictionary of key/value pairs. /// </summary> public IReadOnlyDictionary<string, object> EventData { get { return this._eventData; } }
7.3 Scoring Output Service The Scoring Output service is used to get scores, get history of point changes, and to get achievements.
7.3.1 CumulativeScore [HttpGet] public EntityScore GetScore(string entityID, EntityType entityType) public enum EntityType : short { /// <summary>The entity is of an unknown type.</summary> Unknown = 0, /// <summary>The entity is a user of the Unified Workforce system.</summary> User = 1, /// <summary>The entity is a vendor providing services to Unified Workforce users.</summary> Vendor = 2, }
7.3.2 Achievements [HttpGet] public async Task<AchievementsResult> GetAchievements(string entityID, EntityType entityType)
7.3.3 ManipulationHistory public PointManipulationEventsResult Get(string entityID, int entityType, int pageNumber, int pageSize)
7.4 Code Example An example of submitting an event to the service can be found in the SDK.L4 sample applications. Points are added when adding a new contact.
On submit, the SendSocialStandingEvent is called. public async Task<ActionResult> Index(ManageContacts contacts) { contacts.NewContact.DateCreated = DateTime.UtcNow; Entities.ContactContext context = new Entities.ContactContext(); context.Contacts.Add(contacts.NewContact); context.SaveChanges(); await SendSocialStandingEvent(contacts.NewContact.ContactId, 10011);
7.5 Extraction Agent Points can be extracted from external systems and added to the points from internally generated events. These agents are created in the ExtractionAgentWorkerRole. The current implemented extraction agent supports Word Press integration with abmlq.com. Additional agents could be created to support other systems by implementing a new agent. Implementing an agent requires creating an Extractor, Translator, and Scheduler. At a high level the extraction agent 1. Stores the last extracted event time in the configuration tables 2. Uses that time to pass through to the external system to get any new events since the last run time. 3. Translates the external system UserID to the UW UserID, and point value into the PointChangeEntry class. 4. Saves the PointsChangeEntry collection to the point database. 5. Saves the report to the extraction configuration tables for the next run.
The ExtractionAgentWorkerRole is part of the SocialStanding solution:
7.5.1 Configuring Extraction agents are configured as External Systems in the Admin portal. The external systems that have extraction agents are hard coded in the Run method of the WorkerRole.cs class. To add another agent, this method will need to be modified. public override void Run() { IList<IExtractionAgent> extractionAgents = new List<IExtractionAgent>(); IExtractionAgentConfigurationRepository extractionAgentConfigurationRepository = Application.Container.Resolve<IExtractionAgentConfigurationRepository>(); var extractionAgentConfiguration = extractionAgentConfigurationRepository.GetConfiguration(); var abmlqAgentConfiguration = extractionAgentConfiguration.ExternalSystems.Where(e => string.Compare(e.Name, "ABMLQ", true) == 0).FirstOrDefault();
Finally, after creating the Extractor, Translator, and Scheduler, update ApplicationContainer.cs to add the implemented classes to the IoC container. The name must match the name in the external application. container.RegisterType<IExtractionAgentScheduler, ABMLQExtractionAgentScheduler>("ABMLQ"); container.RegisterType<IExtractionAgentExtractor, ABMLQLExtractionAgentExtractor>("ABMLQ"); container.RegisterType<IExtractionAgentTranslator, ABMLQExtractionAgentTranslator>("ABMLQ");
7.5.2 Extractor The Extractor is responsible for connecting to the source system and translating the point changes into ExternalSystemPointChange objects. This extractor will be fed an instance of PointDataExtraction that contains the last time the agent ran so that only incremental changes are loaded. To create an Extractor implement IExtractionAgentExtractor. Example from abmlq: /// <summary> /// Performs the extraction. /// </summary> /// <param name="pointDataExtractionOfLastRun">The point data that was retrieved the last time this extractor ran.</param> /// <returns>A collection of <see cref="ExternalSystemPointChange"/> objects retrieved from ABMLQ.</returns> public IEnumerable<ExternalSystemPointChange> Run(PointDataExtraction pointDataExtractionOfLastRun) { abmlquwwordpressEntities abmlqEntities = new abmlquwwordpressEntities(this.ExtractorConfiguration.ConnectionString); long latestRecordPullTimestamp = new DateTime(1970, 01, 01).ToUnixTimestamp(); if (pointDataExtractionOfLastRun != null && pointDataExtractionOfLastRun.Data != null) { ExtractionReportAdditionalData extractionReportAdditionalData = JsonConvert.DeserializeObject<ExtractionReportAdditionalData>(pointDataExtractionOfLastRu n.Data); if (extractionReportAdditionalData != null && extractionReportAdditionalData.latestRecordPullTimestamp != null) { long.TryParse(extractionReportAdditionalData.latestRecordPullTimestamp, out latestRecordPullTimestamp); } }
7.5.3 Translator The translator is responsible for converting the points into the Social Standing database schema including mapping the userid from the external systems userid to the UW userid and saving them to the social standing database. To create a Translator implement ABMLQExtractionAgentTranslator. Example from abmlq: /// <summary> /// Performs any translations necessary and writes data back to Social Standing /// </summary> /// <param name="pointChanges">A collection of point change data from the external system.</param> /// <returns>The number of <see cref="ExternalSystemPointChange"/> objects that were processed.</returns> public int Run(IEnumerable<ExternalSystemPointChange> pointChanges) { if (pointChanges != null && pointChanges.Count() > 0) { List<PointChangeEntry> pointChangeEntries = new List<PointChangeEntry>(); var abmlqPointManipulationEventDescriptionDictionary = this._adminService.GetABMLQPointManipulationEventDescriptionMap(); string description = Description; var userIdsMap = this._adminService.GetUserIDsByABMLQUsernames((from p in pointChanges group p by p.UserName into grouped select grouped.Key).ToList()); foreach (var pointChange in pointChanges) { if (abmlqPointManipulationEventDescriptionDictionary.ContainsKey(pointChange.Description)) { description = abmlqPointManipulationEventDescriptionDictionary[pointChange.Description]; } if (userIdsMap.ContainsKey(Convert.ToString(pointChange.UserName))) { pointChangeEntries.Add(new PointChangeEntry(userIdsMap[Convert.ToString(pointChange.UserName)], Domain.Common.EntityType.User, pointChange.PointValue, PointChangeType.Points, pointChange.ChangeDateTime, new PointManipulationEvent(userIdsMap[Convert.ToString(pointChange.UserName)], Domain.Common.EntityType.User, pointChange.ChangeDateTime, null, EventType, pointChange.PointValue, PointChangeType.Points, description))); } } _entityScoreRepository.AddScoreChangeInBatch(pointChangeEntries); return pointChangeEntries.Count();
7.5.4 Scheduler Finally, a Scheduler is created to specify how frequently to run the extraction agent. To create a scheduler, implement IExtractionAgentScheduler. Example from abmlq: /// <summary> /// Starts the scheduler running. /// </summary> public void Run() { while (true) { this.SchedulerTriggered(this, null); int intervalInSeconds = DefaultInterval; if (this.SchedulerConfiguration != null) { int.TryParse(this.SchedulerConfiguration.Interval, out intervalInSeconds); } Thread.Sleep(intervalInSeconds * 1000); } }
8 Work Order Management (WOM) 8.1 About Work Order Management Prerequisites: Admin Portal, WCF, Understanding of 3rd Party Work Order System, Data Mapping. Unified Workforce has been designed to integrate with multiple different work order management systems. These systems all need to provide service layer integrations that Unified Workforce can communicate with. The integrations are hooked into Unified Workforce (UW) through the WOMProxyAgent and the WOMProxy. The WOMProxyâ&#x20AC;&#x2122;s role is to translate the generic message from UW to the specific web service interface provided by a given work order management system.
The primary purposes of the WOM Service Agent is to translate the external systemâ&#x20AC;&#x2122;s data schema to the UW canonical schema. An example worksheet is here in source control for assisting with the process of mapping the data: $/ABMUW/Documents/Corrigo/Reviewed_ABM to WOM Attribute Mappings 12 09 2013.xlsx.
8.2 The WOMProxy The WOMProxy is a web service interface that can be used to communicate out to multiple work order management systems. Agents hosted inside of the WOMProxy are responsible for translating the data to/from the standard canonical format of UW. Additional work order management systems can be implemented and configured.
8.3 WOMProxyAgent & WOMProxyClient The WOMProxy is accessed through the WOMProxyAgent which utilizes the WOMProxyClient to make the web service calls. The WOMProxyClient can also be used directly. The service Uri for the WOMProxy must be configured in the hosting application in order for the WOMProxyClient to know which site hosts the web service. For local development in app.config: <add key="WOMProxyServiceUri" value="http://abmuwwomproxyint.cloudapp.net/ProcessMessage" /> <add key="WomProxyEnabled" value="true" />
In Azure environment in ServiceConfiguration: <Setting name="WOMProxyServiceUri" value="http://abmuwwomproxyint.cloudapp.net/ProcessMessage" /> <Setting name="WomProxyEnabled" value="true" />
8.3.1 Service Interface The WOMProxy ProcessMessage method accepts a RequestInfo object. The request will define the WOM System(s) that should receive the request and the operation to perform. The method will return a ResponseInfo object that contains the results of the operation.
// Create extended properties to be passed to Maximo Agent var extendedProperties = new List<ExtendedProperty> { new ExtendedProperty { Name = KnownConstants.Workordernumber, Value = "3083" }, new ExtendedProperty { Name = KnownConstants.WOMSystem, Value = "Maximo"}, }; // Create a generic entity object and associate the extended properties to the object, all other properties can be set to Null or Empty var requestBodyEntity = new List<Workorder> { new Workorder { // Assign the extended properties collection ExtendedProperties = extendedProperties, // Mark other properties are empty Id = string.Empty, Value = string.Empty, Name = string.Empty, Description = string.Empty, Createdby = DateTime.Now.ToString(System.Globalization.CultureInfo.InvariantCulture) } }; // Serialize the Generic Entity collection to pass it as part of the request var requestBodyXml = new Serializer<Workorder>().Serialize(requestBodyEntity, SerializerType.XmlSerializer).ToString(); var requestBodyXlement = XElement.Parse(requestBodyXml); // Pass the serialized form of Generic Entity collection var requestBody = new MessageInfo { MessageBody = requestBodyXlement }; // Prepare the request object var requestHeader = new MessageInfo { MessageBody = null }; // Header not required for SC AGent var requestInfo = new RequestInfo { Header = requestHeader, Body = requestBody, TargetService = new TargetServiceInfo { OperationName = KnownConstants.GetWorkOrder }, }; ResponseInfo responseInfo = womProxy.ProcessMessage(requestInfo);
8.3.2 Client Proxy Examples Example are available in the SDK under the CodeSamples project.
8.4 Creating a WOM Proxy Agent 8.4.1 Overview At a high level, a WOM Proxy Agent consists of the Agent, the Service Operations, the Mapper, and the Configuration.
The SDK provides a basic skeleton of how a new WOM Proxy Agent can be created under the CodeSamples project.
8.4.2 WOM Agent (IAgent) The Service Agent is the entry point and will determine the correct service operation that needs to be called. public UW.Schema.ResponseInfo Process(UW.Schema.RequestInfo requestInfo) { //First validate required fields Check(requestInfo); var responseInfo = default(ResponseInfo); switch (requestInfo.TargetService.OperationName) { //Get work order handles all of the get operations (status, date, user, etc) //The client proxy will send this operation through for all gets case KnownConstants.GetWorkOrder: responseInfo = sampleWOMServiceOperations.GetWorkOrder(requestInfo); break;
8.4.3 WOM Service Operations (WorkOrderServiceOperationBase) WOM Operations provide the control-flow for transforming the request, making the external web service call, and transforming the response. //class that makes the external web service calls, maps the data and returns it public class SampleWOMServiceOperations : WorkOrderServiceOperationBase { private string serviceAgentName; private SampleAgentConfig sampleAgentConfig; private SampleAgentMapper sampleAgentMapper; public SampleWOMServiceOperations(string serviceAgentName) { this.serviceAgentName = serviceAgentName; sampleAgentConfig = new SampleAgentConfig(serviceAgentName); sampleAgentMapper = new SampleAgentMapper(); } public ResponseInfo GetWorkOrder(RequestInfo requestInfo) { var request = sampleAgentMapper.TranformGetWorkOrderRequest<object>(requestInfo, sampleAgentConfig); //TODO: make web service call passing in transofmed web request var webServiceResponse = new object(); var response = sampleAgentMapper.TranformGetWorkOrderResponse(webServiceResponse, sampleAgentConfig); return response; }
8.4.4 WOM Service Configuration (ConfigBase) WOM Configuration reads configuration from the Admin database including the Status mappings so that this information is accessible by other components.
//Class that pulls status mapping and service agent configuration public class SampleAgentConfig : ConfigBase { #region Private Members private ConfigReader agentConfigReader; private List<AgentConfig> config; private List<WOMStatusMap> womstatusmap;
8.4.5 WOM Agent Mapper (AgentMapperBase) WOM Mapper transforms the RequestInfo class into the object being expected by the 3rd party WOM System and transforms the response from the 3rd party WOM System to a ResponseInfo class. //Used to transform data to/from 3rd party WOM System, use the ageentConfig to transform statuses to the cononical statuses. public class SampleAgentMapper: AgentMapperBase { //Create the outbound request object to be sent to the 3rd party WOM system public override T TranformCreateWorkOrderRequest<T>(RequestInfo requestInfo, ConfigBase agentConfig) { throw new NotImplementedException(); }
8.5 Configuration An entry must be added under WOM Configuration.
8.5.1 Status Mapping The WOMProxy was designed to map data to a canonical schema so that different statuses with the same meanings can be mapped to a standard. This mapping is defined in the Status Map tab of WOM Configuration.
In the case of multiple fields being required for the mapping. Multiple filters can be stored in the WOM Status field. Format of WOM Status field: [Status]:[Field][Operator][Value], [Field2][Operator2][Value2]
8.5.2 Site Mapping The site (location/office) must also be mapped between what is configured within the work order system and UW. This mapping is defined in the Site tab of WOM Configuration. Select the Organization and enter the WOM Site name.
8.5.3 Userâ&#x20AC;&#x2122;s profile When configuring the user, there is a setting that needs to be defined for WOM in UW to function properly. The UwTechID User Attribute defines the user name for this user inside of the external work order system.
9 Level 4 Application Single Sign on 9.1 About the authentication model Prerequisites: Admin Portal, Azure AD Access Control, Federated Authentication, SAML. Applications in UW use Windows Identity Foundation (WIF) and Federated Authentication for their authentication. There are no password databases maintained directly by UW. The basic flow for authentication is as follows: 1. Users are redirected to one of several identity providers (live, azure ad, google, etc) for authentication. 2. After authentication, UW uses Windows Azure access control for the Federation Provider for issuance of the WIF token which then redirects back to the application. 3. Federated Authentication will read the token and create a cookie that will subsequently be passed on future requests so the user does not need to re-authenticate. A certificate is required for the validation of the token. 4. Custom claims manager will map the userâ&#x20AC;&#x2122;s ID to the admin database User. Windows Live ID has special handling due to lack of a user name being passed back in the token. For more information on using Azure as the Federation Provider: http://www.windowsazure.com/en-us/documentation/articles/active-directory-dotnet-how-to-useaccess-control/ For more information on how federated authentication works within the application: http://msdn.microsoft.com/en-us/magazine/ff872350.aspx
9.2 Setting up azure active directory access control Azure Active Directory Access Control is used as the Federation Provider. For any environment, including local development, a directory access control should be setup. 1. Create a new service namespace. 2. Manage the namespace. 3. Create a relaying party application with the return URL and Realm for your environment and each app you need to login to. a. In a production environment this is just Metro Wrapper. For local development you may consider allowing login directly to your application(s). b. Provide the ABM code signing certificate. 4. Auto generate rules for the rule group that was assigned. For full instructions on setting access control up in Azure Management Portal: http://msdn.microsoft.com/en-US/library/gg429779.aspx
9.3 Setting up your application for authentication 9.3.1 References 1. The Microsoft Token Validation Extension must be installed from NuGet.
2. References to System.IdentityModel are required
9.3.2 Web.config settings 1. Under system.webserver we disable forms authentication and enable federated authentication. <modules> <remove name="FormsAuthentication" /> <add name="WSFederationAuthenticationModule" type="System.IdentityModel.Services.WSFederationAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" preCondition="managedHandler" /> <add name="SessionAuthenticationModule" type="System.IdentityModel.Services.SessionAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" preCondition="managedHandler" /> </modules>
2. Create new sections for system.identityModel and point to your applications url and the federation provider. a. CustomClaimsManager is used instead of the default manager in order to do the mapping to the admin database user. The CustomClaimsManager will look up the user by email address (NameIdentifier in the case of Windows Live). Additional claims such as the UserId and First and Last name are added. b. Note: CustomClaimsManager only needs to be in the main Metro Wrapper application however; for local development, it is helpful to include it so you can work with your application independently. <system.identityModel> <identityConfiguration> <audienceUris> <add value="https://localhost:44300" /> </audienceUris> <issuerNameRegistry type="System.IdentityModel.Tokens.ValidatingIssuerNameRegistry, System.IdentityModel.Tokens.ValidatingIssuerNameRegistry"> <authority name="https://slalomlocaldev.accesscontrol.windows.net/"> <keys> <add thumbprint="9FE7C34F8551F317E345753E030A102AE935AD33" /> </keys> <validIssuers> <add name="https://slalomlocaldev.accesscontrol.windows.net/" /> </validIssuers> </authority> </issuerNameRegistry> <!--certificationValidationMode set to "None" by the the Identity and Access Tool for Visual Studio. For development purposes.--> <certificateValidation certificateValidationMode="None" /> <claimsAuthenticationManager type="ABM.SDK.L4.CustomClaimsManager, ABM.SDK.L4" /> </identityConfiguration> </system.identityModel> <system.identityModel.services> <federationConfiguration> <cookieHandler requireSsl="true" /> <wsFederation passiveRedirectEnabled="false" issuer="https://slalomlocaldev.accesscontrol.windows.net/v2/wsfederation" realm="https://localhost:44300" requireHttps="true" /> </federationConfiguration> </system.identityModel.services>
3. Set the MachineKey setting to be the same as all other applications deployed in the environment. You can copy this setting from the Metro Wrapperâ&#x20AC;&#x2122;s web.config. This is required for asp.net cookies to be decrypted:
<machineKey decryption="AES" decryptionKey=" " validation="SHA1" validationKey="" />
4. If in a live azure environment (not localhost), configure cookies to be issued cross-domain <httpCookies domain =".cloudapp.net"
xdt:Transform="Replace" httpOnlyCookies="true"/>
9.4 Securing controllers and controller methods The filter attribute AuthorizeUserAccess needs to be added to the top of each controller that needs to be secured. If not all methods in a controller are secured, add the attribute above each individual controller method instead. This filter does a redirect to the L1 page of the Metro Wrapper application so it can handle the login process. public class HomeController : Controller { [AuthorizeUserAccess] public ActionResult Index(string returnUrl) { ViewBag.ReturnUrl = returnUrl; return View(); } }
9.5 Adding Federation Configuration to global.asax In order for federated authentication claims to be validated across instances, a security token handler must be registered in the global.asax.cs. Add the following configuration:
protected void Application_Start() { FederatedAuthentication.FederationConfigurationCreated += this.OnFederationConfigurationCreated;
protected void OnFederationConfigurationCreated(object sender, FederationConfigurationCreatedEventArgs e) { var sessionTransforms = new List<CookieTransform>( new CookieTransform[] { }); var sessionHandler = new SessionSecurityTokenHandler(sessionTransforms.AsReadOnly()); if (e != null) { e.FederationConfiguration.IdentityConfiguration.SecurityTokenHandlers.AddOrReplace(sessio nHandler); } }
9.6 Adding the UserInfo class for simplified access to the current Identity For simplified access to common claim information like UserId, Email, and Name, use the UserInfo class. public class UserInfo { private readonly ClaimsIdentity identity; public UserInfo() { this.identity = null == HttpContext.Current || null == HttpContext.Current.User ? null : (ClaimsIdentity)HttpContext.Current.User.Identity; } public UserInfo(HttpContext httpContext) { this.identity = null == httpContext || null == httpContext.User ? null : (ClaimsIdentity)httpContext.User.Identity; } public string Email { get { return Convert.ToBoolean(UnifiedResourceReader.GetSettingValue(ConfigurationKeys.IsDebugConfigur ation).ToValueString(), CultureInfo.InvariantCulture) ? UnifiedResourceReader.GetSettingValue(ConfigurationKeys.Email).ToValueString().ToLowerInv ariant() : this.GetClaimValue(ClaimTypes.Email).ToLowerInvariant(); } }
9.7 Creating a login page for testing In production, your application will redirect to the Metro Wrapper for authentication. This will require you to have the Metro Wrapper up and running in your local environment. For development purposes, it is useful to have a redirect to Azure Active Directory Access Control for logging into your L4 app without going through the Metro Wrapper. This sample does not onboard new users, it is assumed the user has already been created in the copy of the Admin database being used.
1. Create a controller method and view that does not require authentication to access (in this example Login controller and View). 2. From the Active Directory Access Control portal, copy the URL for your application and place it as a link on your view. 3. Access the view from the browser and click the link. It will redirect you to Active Directory Access Control for login. 4. If you have your web.config setup correctly, and the user already exists in the Admin database, the authentication will work seamlessly when you are redirected back your app.
10 External Application Single Sign on 10.1 About External Applications Prerequisites: Admin Portal, Salted Hashing. Users of Unified Workforce can access external systems such as ABMLQ and Venu. When a user is created inside of Unified Workforce their credentials can be synced with these systems so they are not required to login again when accessing them. Service agents are used to communicate the sync between the external web service and the admin portal for syncing.
From inside the Metro Wrapper, tiles can launch the external application URLs. For Single Signon to occur, the hashed userID is passed.
10.2 Syncing in Admin Portal External applications are configured in the Admin Portal. They include the application name, logo, version, the type of external application and the service agent used to communicate with the external system.
The syncing of the app for a specific user is done in the External Application section of the User Configure screen:
Clicking the Sync button will make a web service call to that system to create the user. When the user accesses that system from inside Unified Workforce their hashed credentials are passed through and they are automatically signed on.
10.3 Live Tile Configuration Under the live tile configuration, the Launch URL needs to have expressions that are found and replaced at run time by the live tile. For example for Venu:
10.4 External Website SSO Support For this method of authentication to work, the external website being integrated with will need to provide: 1) Landing page that accepts the UserID hash and authenticates the user based on that hash. 2) Web service that will allow for the creation and update of users.
10.5 Creating a Service Agent Service agents are used by the admin portal to communicate with the external web services when syncing accounts. See chapter on Service Agents for more information on service agents. An example of the ABMLQ service agent used by the Admin the source can be found here: $/ABMUW/Main/Source/ABM.Admin/Communication.Agents.Venu
10.6 Adding a Service Agent to Admin Portal The Admin Portal has been designed to sync the accounts through a Service Agent. These agents are directly referenced by the Admin portal and are not accessed through the Message Processor. The code is found in two places. One on the click of the green Sync button and the other on the Save. Based on the name of the application, the corresponding Agent is called. This is hard coded so any additional Agents will need to be added in both places in the admin portal. The existing pattern can be followed handling the manual sync on the sync button click and the auto sync on the Save button click.
//Code sample from rgExtApplication_ItemCommand if (lblApplication.Text.Equals("Venu", StringComparison.CurrentCultureIgnoreCase)) { var tempuser = _entity.Users.Where(p => p.Id == userId).FirstOrDefault(); if (tempuser != null) { if (!tempuser.IsActive) { lblExtAppErrorMessage.Text = "User is not active"; lblExtAppErrorMessage.ForeColor = System.Drawing.Color.Red; } else { SynchItemForVenu(userId, true); } } }
//Code sample from SyncItemForVenu var requestInfo = new RequestInfo { Header = requestHeader, Body = requestBody, TargetService = new TargetServiceInfo { AgentName = "Venu", ContractName = "", OperationName = "CreateUpdateUser" }, }; var response = agent.Process(requestInfo);
11 Deployments Unified Workforce components can be deployed manually or through available automated build scripts. Automated build scripts are available for integrated and production environments. These scripts upload to the Azure roles in staging. As a practice, the production roles are deleted prior to beginning to prevent worker roles that were designed to run in a single instance from causing data corruption.
11.1 Merge to Main and Label The first step is to ensure all partners have merged their changes into the Main branch. All releases occur from Main. As a best practice, create a label in the development branch and merge based on label. This ensures change sets that happen later are not accidentally merged.
11.2 Deployment Documents Deployment documents are created for every release. These documents are used as a reference for the build manager while doing the release. These documents reference the following:
The deployment schedule/process being followed Build environment Configuration File Names – Critical that these are correct – any new cloud projects in the build must be added. SQL scripts that need to be run URLs for each component in the environment New Features Bugs Fixed Known Issues Smoke Test & Test Results
Documents can be found in the following location: $/ABMUW/Documents/Deployment
11.3 Editing Build Configuration The build configuration names and target projects must be added to the configuration file created for the automated builds. This BuildInput.xml file can be found here: $/ABMUW/Main/BuildProcessTemplates/ABM_Int_Test The target configuration profile can be found under GlobalInputArguments. <IndividualMSBuildArgumentsForItemsToBuild>/p:TargetProfile="ABM Integration" /p:Configuration="ABM Integration" /p:PlatForm="Any CPU"|/p:TargetProfile="ABM Integration" /p:Configuration="ABM Integration" /p:PlatForm="Any CPU"|/p:TargetProfile="ABM Integration" /p:Configuration="ABM Integration" /p:PlatForm="Any CPU"|/p:TargetProfile="ABM Integration" /p:Configuration="ABM Integration" /p:PlatForm="Any CPU"|/p:TargetProfile="ABM Integration" /p:Configuration="ABM Integration" /p:PlatForm="Any CPU"|/p:TargetProfile="Test" /p:Configuration="Test" /p:PlatForm="Any CPU"|/p:TargetProfile="Test" /p:Configuration="Test" /p:PlatForm="Any CPU"|/p:TargetProfile="Test" /p:Configuration="Test" /p:PlatForm="Any CPU"|/p:TargetProfile="Test" /p:Configuration="Test" /p:PlatForm="Any CPU"|/p:TargetProfile="Test" /p:Configuration="Test" /p:PlatForm="Any CPU"|/p:TargetProfile="Test" /p:Configuration="Test" /p:PlatForm="Any CPU"|/p:TargetProfile="Test" /p:Configuration="Test" /p:PlatForm="Any CPU"|/p:TargetProfile="Test" /p:Configuration="Test" /p:PlatForm="Any CPU"|/p:TargetProfile="ABM.UW.NEU.INT" /p:Configuration="ABM.UW.NEU.INT" /p:PlatForm="Any CPU"|/p:TargetProfile="ABM.UW.NEU.INT" /p:Configuration="ABM.UW.NEU.INT" /p:PlatForm="Any CPU"</IndividualMSBuildArgumentsForItemsToBuild>
The build configuration information can be found under InputArguments. Project configuration information must be in the same order for all 5 parameters.
<InputArguments> <Add Key="selectedsubscription" Value="UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test|UW Integrated Test" ShowInReport="true"/> <Add Key="storageAccountName" Value="msftdeployspace|msftdeployspace|msftdeployspace|msftdeployspace|msftdeployspace|ms ftdeployspace|msftdeployspace|msftdeployspace|msftdeployspace|msftdeployspace|msftdeploys pace|msftdeployspace|msftdeployspace|msftdeployspace|msftdeployspace|msftdeployspace|msft deployspace" ShowInReport="true"/> <Add Key="serviceName" Value="abmeserviceint|abmwebconsoleint|abmcommunicationint|abmuwscint|abmuwscworkerint|ab muwadminportalint|abmuwwomproxyint|abmuwcontlearnint|abmuwsocstandint|abmmessagebusservic eint|abmsduiint|abmuwcommunicationbusint|abmsdint|abmsdprocessorint|abmuwworkflowmanageri nt|abmuwpomint|abmscheduledjobworkerint" ShowInReport="true"/> <Add Key="SelectedPackageFileName" Value="EServiceCloudUI.cspkg|WebConsoleCloud.cspkg|Communication.HostedService.cspkg|ABM. SC.Service.cspkg|ABM.SC.Worker.cspkg|AdminPortal.Azure.cspkg|WOMProxy.CloudService.cspkg| ContextualLearningCloudService.cspkg|CommunityPointsCloudService.cspkg|MessageBus.cspkg|S ocialDispatchCloudUI.cspkg|CommunicationBusCloud.cspkg|SocialDispatchCloudService.cspkg|S ocialDispatchProcessorService.cspkg|WorkflowManagementServiceCloud.cspkg|ABM.UW.POMCloudS ervice.cspkg|ScheduledJobWorker.cspkg" ShowInReport="true"/> <Add Key="SelectedCloudConfigFileName" Value="ServiceConfiguration.Test.cscfg|ServiceConfiguration.Test.cscfg|ServiceConfigurati on.Test.cscfg|ServiceConfiguration.ABM Integration.cscfg|ServiceConfiguration.ABM Integration.cscfg|ServiceConfiguration.ABM Integration.cscfg|ServiceConfiguration.ABM Integration.cscfg|ServiceConfiguration.ABM.UW.NEU.INT.cscfg|ServiceConfiguration.ABM.UW.N EU.INT.cscfg|ServiceConfiguration.Test.cscfg|ServiceConfiguration.Test.cscfg|ServiceConfi guration.Test.cscfg|ServiceConfiguration.Test.cscfg|ServiceConfiguration.Test.cscfg|Servi ceConfiguration.Test.cscfg|ServiceConfiguration.ABM Integration.cscfg|ServiceConfiguration.Test.cscfg" ShowInReport="true"/> </InputArguments>
If there are any changes to this file, ensure the file is checked in prior to beginning a build.
11.4 Archive Existing Deployments For Production deployments, rollbacks should be created by archiving the existing Production deployments prior to starting the deployment process.
11.5 Deleting Existing Deployments Prior to starting the build, the existing Azure instances being deployed to should have their deployments deleted. Not all instances should be deleted. The instances that should have their deployments deleted are the ones listed in the serviceName parameter in BuildInput.xml. From the main cloud services page, left click each service, select the delete button and then the production/staging deployment (do not the whole service). You do not need to wait for the delete operation to complete before moving on to the next service.
11.6 Delete Service Bus Queue All Queues under the service bus should be deleted prior to deployment. During deployment, they will be recreated.
11.7 Cleaning temporary databases Log databases should be cleared prior to releasing.
11.8 Ensure Correct Certificates Certificates need to be uploaded to the Azure instances prior to deployment. The Cloud Projects should also be checked to ensure they have the most recent version of the certificate and not old versions.
Certificates in Azure:
Certificates in Azure Service Configuration files: <Certificates> <Certificate name="HttpsEndPoint" thumbprint="9FE7C34F8551F317E345753E030A102AE935AD33" thumbprintAlgorithm="sha1" /> </Certificates>
The latest certificate can be found here: $/ABMUW/Documents/Certificates/ABM/UW2013 - Update
11.9 Automated Build Scripts Automated build templates have been created for building and deploying into the Azure environments. To start a new build right click on the build definition and Queue a new build. ABM_Int_TEST will build into the Integrated environment. Ensure all of the solutions to build are included by editing the build definition.
Then queue a new build.
The definition for this deployment can be found here in source control: $/ABMUW/Main/BuildProcessTempaltes/ABM_Deploy_Config_new.xaml
11.9.1 Build Definitions Build Name ABM_int_TEST ABM_Production ABM_Production_Test
Description Build & Deploy into Integrated Azure environment Build & Deploy into Production Azure environment Build only packages for Production Azure environment
11.10 Manual upload if deploy fails If the build succeeds but the deployment into the environment fails, a manual upload is possible using the Azure admin portal. Remote desktop into the ESPOCMET1 build server (VPN required) and log into the Azure Management Console. For each service instance that did not finish deploying, select the instance.
Perform a new staging deployment upload.
Browse for the deployment package and configuration file from the build drop folder.
11.11 Swap Staging Instances After all staging instances have been deployed to successfully, the last step is to swap the instances into the Production environment. From the Cloud Services main page. Single left-click each instance and click the Swap button. You do not need to wait for the swap operation to finish before moving on to the next service.
12 Validating Performance Changes to the UW platform that could affect performance need to be evaluated to ensure load times are not affected. The performance of the application should be checked twice and compared. Once before changes are deployed and once after changes are deployed. One way to accomplish this is through the use of Chrome Dev Tools and Fiddler. Fiddler provides an excellent overview of network load times including total time and total bytes sent/received. Chrome Dev Tools provides an excellent overview of load times within the browser itself including JavaScript and rendering. Chrome: www.google.com/chrome Fiddler: www.telerik.com/download/fiddler
12.1 How to Profile This guide will provide step-by-step guidance on how to profile the application using these tools. In this example, the application being checked is Metro Wrapper.
12.1.1 Log Into the Application Using Chrome, log into the application that is being tested.
12.1.2 Open the Timeline View Hit F12 and select the Timeline tab. Clear any existing data if present.
12.1.3 Open Fiddler Open Fiddler and attach it to the instance of Chrome by dragging the “Any Process” menu bar on top of the instance of Chrome. In this example the process target changes to “Chrome:772”. Clear any existing data and stop recording by going to File > Capture Traffic.
12.1.4 Recording 1. In Fiddler, start the recording by going to File > Capture Traffic 2. In Chrome timeline view, start the recording.
3. Refresh the Page in Chrome. 4. Watch Fiddler to ensure all scripts and asynchronous loads have finished. 5. Stop the Recording in Chrome
6. Stop the Recording in Fiddler by going to File > Capture Traffic
12.2 Analyze the results The record process should be run twice once for before the change and once for after the change and the results compared.
12.2.1 Fiddler To save the results for Fiddler, select all of the events in the left-hand view and then select the Statistics tab. The results can be copy/pasted into a document and saved. You can save the entire session for later analysis by selecting File > Save > All Sessions. Request Count: Unique Hosts: Bytes Sent: Bytes Received:
208 11 1,171,267 1,672,278
ACTUAL PERFORMANCE -------------Requests started at: Responses completed at: Sequence (clock) duration: Aggregate Session duration: DNS Lookup time: TCP/IP Connect duration: HTTPS Handshake duration:
(headers:898,763; body:272,504) (headers:45,534; body:1,626,744)
11:20:44.022 11:21:49.774 00:01:05.752 00:05:00.905 953ms 1,181ms 3,192ms
The key metrics to capture here are Sequence duration, Bytes Sent, and Bytes Received.
12.2.2 Chrome To save the results for Chrome, on the Timeline view use the timeline sliders to select all of the events. Select the Details graph and save it into a document. You can save the entire session for later analysis by right clicking and selecting Save Timeline Data. 54.000 ms Loading 2.78 s Scripting 15.000 ms Rendering 276.000 ms Painting 872.010 ms Other 1.1 min Idle
They key metrics to capture here are loading, scripting, rendering and painting.
12.2.3 Compare Results After saving the results for the before and after captures, compare the results. If the results show a significant increase, analyze the detail of the captures in further detail to help identify the cause.