Introduction

Field Engineer helps mobile field agents keep track of work assignments, complete with destination routing and inventory management. The application allows an agent to view currently assigned tasks and to capture customer signoff when the job is complete, even when offline.

A complete version of the app is available for viewing in the Windows Store.

Building the Sample

Tools needed

 - Visual Studio 2013 (http://www.visualstudio.com/en-us/downloads)
 - Windows Store Developer account (https://appdev.microsoft.com/StorePortals/en-US/Account/signup/start)
 -  Azure Subscription (http://azure.microsoft.com/en-us/)

Building Solution

- Install Bing Maps Extension (http://visualstudiogallery.msdn.microsoft.com/224eb93a-ebc4-46ba-9be7-90ee777ad9e1)
- Install SQLite for Windows 8.1 (http://visualstudiogallery.msdn.microsoft.com/1d04f82f-2fe9-4727-a2f9-a2db127ddc9a)
- Open AzureMobile.Samples.FieldEngineer.sln and build solution. This will download all the required nuget package references

 

Mobile Service Setup

1. Create New MobileService with new database on Azure Portal (https://manage.windowsazure.com/)
2. Register an app with windows store (http://msdn.microsoft.com/en-US/windows/apps/br211386)
3. Setup Push credentials (http://msdn.microsoft.com/en-us/library/azure/jj591526.aspx)

Azure Active Directory Setup

1. Follow instructions at Single Sign on with AAD (http://azure.microsoft.com/en-us/documentation/articles/mobile-services-windows-store-dotnet-adal-sso-authentication/) to setup AAD native app.
2. Follow instructions AAD authentication with Mobile Service (http://azure.microsoft.com/en-us/documentation/articles/mobile-services-how-to-register-active-directory-authentication/ ) to use AAD authentication with MobileService
3. Go to configure page for the AAD Web App created above:
 (This App will be used to update/read information about AAD users)
 -  Update permissions to include all the delegated permissions.
 -  Update permissions to include Read and Write Directory Data Application Permissions.
 -  Create a key. **Make sure you save the key created at this step. We will need this later**
 
4. GO to Groups tab on AD and create two groups:
    - FieldAgents
    - Managers
5. Save following information from the AD:

 - Go to FieldAgent group configure page. Get the object id for the group.
 - Go to Manager group configure page. Get the object id for the group.
 - Go to Domains page for directory. Get the default domain.

 

Create Active Directory Users


1. Go to Users tab, create a minimum of **3** users. Once the user is created add alternate email address on profile tab.
2. Go to FieldAgents Group and Add 2 members
3. Go to Managers Group and 1 member

Jobs in database are equally distributed among the users in FieldAgents. You can increase the number of users to suit your needs.


Database setup

1. Open AzureMobile.Samples.FieldEngineer.Setup project and update following in App.config:
  - AadTenantDomain : Your Active Directory Domain name. Get this from Domains tab on your directory. This looks like: xxxxxxxx.onmicrosoft.com
  - MS_AadClientID: Client id for the Web App you setup
  - AadServiceAppKey: Key you saved earlier in Active Directory Setup
  - AadFieldAgentGroupObjectId: ObjectId for FieldAgents Group. You can get this from FieldAgents Group configure page
  - AadFieldManagerGroupObjectId: ObjectId for Managers Group. You can get this from Managers Group configure page
  - MS_TableConnectionString : SQL Azure Connection string. Get ADO.Net connection string from Azure SQL DB Dashboard.
  - MS_MobileServiceName: The name you used when creating the mobile service
  - Run the project, and paste in the Master Key for your mobile serivce when prompted. The master key can be found by clicking "Manage Keys" while on the dashboard page of the Mobile Services Management Portal.

 

(Optional) Enable app analytics with Microsoft-owned Capptain.com

1. Register your application according to the instructions on http://www.capptain.com/ and obtain an Application ID and an SDK Key.
2. In CapptainConfiguration.xml, replace "ReplaceWithYourApplicationId" with the Application ID you obtained during registration.
3. Replace "ReplaceWithYourSDKKey" with the SDK Key you obtained during registration.

Publish Mobile Service

1.  Add following AppSettings from Mobile Service from Configure page on Azure Portal(https://manage.windowsazure.com)
 - Key: AadFieldAgentGroupObjectId Value: Object Id for the FieldAgents group
 - Key: AadFieldManagerGroupObjectId Value: Object Id for the Managers group
 - Key: AadTenantDomain Value: AAD Domain
 - Key: AadServiceAppKey Value: This is the key from AD Web App  

2. To send email when job is completed, set up SendGrid account and add following AppSettings in MobileService:
 - Key: SendGridUserName value: SendGrid account user name
 - Key: SendGridPassword value: Send grid account password
 - Key: SendGridFromEmailId value: Address from which you Email will be sent
 - Key: SendGridFromEmailUserName value: Your name

 
3. Publish Service to the MobileService you created. To see how to publish take a look at "Publish Your Mobile Service" section in this article (http://azure.microsoft.com/en-us/documentation/articles/mobile-services-dotnet-backend-windows-store-dotnet-get-started/)

 

Run Windows Store App


1. Update following in Secrets.cs:
 - MobileServiceUrl = "https Mobile Service URL";
 - MobileServiceAccessKey = "Mobile Service Application Key";
 - AadDomainName = "AAD Domain Name";
 - AadNativeClientId = "Native App Client ID";

2. Run AzureMobile.Samples.FieldEngineer.Windows project

3. Login using AD user credentials. You can login with any user from FieldAgents group

 

(Optional) FieldEngineerManager

FieldEngineerManager app is a simple MVC app with AAD authentication and connects to Mobile Service to:

Create Job: If the agent new job is created for is logged into client app, it will recieve push notification

 To reset jobs for a selected agent: This is useful if you want to clean up jobs table.

-          AAD Setup

  1. Sign in to the Azure management portal.
  2. Click on Active Directory in the left hand nav.
  3. Click the directory tenant where you wish to register the sample application.
  4. Click the Applications tab.
  5. In the drawer, click Add.
  6. Click "Add an application my organization is developing".
  7. Enter a friendly name for the application, for example "MyFieldEngineerManager", select "Web Application and/or Web API", and click next.
  8. For the sign-on URL, enter the base URL for the sample, which is by default https://localhost:44322/. NOTE: It is important, due to the way Azure AD matches URLs, to ensure there is a trailing slash on the end of this URL. If you don't include the trailing slash, you will receive an error when the application attempts to redeem an authorization code.
  9. For the App ID URI, enter https://<your_tenant_name>/MyFieldEngineerManager, replacing <your_tenant_name> with the domain name of your Azure AD tenant. For Example "https://contoso.com/MyFieldEngineerManager". Click OK to complete the registration.
  10. While still in the Azure portal, click the Configure tab of your application.
  11. Find the Client ID value and copy it aside, you will need this later when configuring your application.
  12. In the Reply URL, add the reply URL address used to return the authorization code returned during Authorization code flow. For example: "https://localhost:44322/"
  13. Under the Keys section, select either a 1 year or 2 year key - the keyValue will be displayed after you save the configuration at the end.
  14. Configure Permissions - under the "Permissions to other applications" section, select application "Windows Azure Active Directory" (this is the Graph API), and under the second permission (Delegated permissions), select "Access your organization's directory" and "Enable sign-on and read users' profiles". The 2nd column (Application permission) is not needed for this demo app.
  15. Select the Save button at the bottom of the screen - upon sucessful configuration, your Key value should now be displayed - please copy and store this value in a secure location. The key value is only displayed once, and you will not be able to retrieve it later.

 Configure Manager app with AAD and run the app

 Open AzureMobile.Samples.FieldEngineer.Manager project and update following in Web.config:

  1. ida:Tenant - Your Active Directory Domain name. Get this from Domains tab on your directory. This looks like: xxxxxxxx.onmicrosoft.com
  2. ida:ClientId - Client id for the Web App you setup
  3. ida:AppKey - Key you saved earlier in Active Directory Setup
  4. MobileServiceUrl- FieldEngineer MobileServiceURL. This looks like https://<NameofMobileService>.azure-mobile.net

Run the project, and login with a user in Manager group