docs: New doc for creating an AfW Work Policy Controller

See first comment for doc stage location.

Change-Id: I0c9c0f849c049d33fc66e2bd8ac5ba284c7b9415

2 files changed, 345 insertions, 1 deletions

diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd
index bed4b4d..45bd76a 100644
--- a/docs/html/guide/topics/admin/device-admin.jd
+++ b/docs/html/guide/topics/admin/device-admin.jd
@@ -48,6 +48,11 @@ solutions for Android-powered devices. It discusses the various features
 provided by the Device Administration API to provide stronger security for
 employee devices that are powered by Android.</p>
 
+<p class="note"><strong>Note</strong> For information on building a Work Policy
+Controller for Android for Work deployments, see <a
+href="{@docRoot}training/enterprise/work-policy-ctrl.html">Building a Work
+Policy Controller</a>.</p>
+
 
 <h2 id="overview">Device Administration API Overview</h2>
 
@@ -712,4 +717,4 @@ mDPM.setStorageEncryption(mDeviceAdminSample, true);
 </pre>
 <p>
 See the Device Administration API sample for a complete example of how to enable storage encryption.
-</p>
\ No newline at end of file
+</p>
diff --git a/docs/html/training/enterprise/work-policy-ctrl.jd b/docs/html/training/enterprise/work-policy-ctrl.jd
new file mode 100644
index 0000000..5854e65
--- /dev/null
+++ b/docs/html/training/enterprise/work-policy-ctrl.jd
@@ -0,0 +1,339 @@
+page.title=Building a Work Policy Controller
+page.metaDescription=Learn how to develop a Work Policy Controller to create and administer a managed profile on an employee's device.
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#after_creating_profile">Create a Managed Profile</a></li>
+ <li><a href="#set_up_policies">Set Up Device Policies</a></li>
+ <li><a href="#apply_restrictions">Apply App Restrictions</a></li>
+</ol>
+
+<!-- related docs (NOT javadocs) -->
+
+<h2>
+  You should also read
+</h2>
+
+<ul>
+  <li>
+    <a href="{@docRoot}guide/topics/admin/device-admin.html">Device
+    Administration</a>
+  </li>
+</ul>
+
+<h2>Resources</h2>
+<ul>
+
+  <li>
+    <a href=
+    "{@docRoot}samples/BasicManagedProfile/index.html">BasicManagedProfile</a>
+  </li>
+
+  <li>
+    <a href=
+    "{@docRoot}samples/AppRestrictionEnforcer/index.html">AppRestrictionEnforcer</a>
+  </li>
+</ul>
+
+</div>
+</div>
+
+
+<p>
+  In an Android for Work deployment, an enterprise needs to maintain control
+  over certain aspects of the employees' devices. The enterprise needs to
+  ensure that work-related information is encrypted and is kept separate from
+  employees' personal data. The enterprise may also need to limit device
+  capabilities, such as whether the device is allowed to use its camera. And
+  the enterprise may require that approved apps provide app restrictions, so
+  the enterprise can turn app capability on or off as needed.
+</p>
+
+<p>
+  To handle these tasks, an enterprise develops and deploys a Work Policy
+  Controller app. This app is installed on each employee's device. The
+  controller app installed on each employee's device and creates a work user
+  profile, which accesses enterprise apps and data separately from the user's
+  personal account. The controller app also acts as the
+  bridge between the enterprise's management software and the device; the
+  enterprise tells the controller app when it needs to make configuration
+  changes, and the controller app makes the appropriate settings changes for the
+  device and for other apps.
+</p>
+
+<p>
+  This lesson describes how to develop a Work Policy Controller app for devices
+  in an Android for Work deployment. The lesson describes how to create a work
+  user profile, how to set device policies, and how to apply
+  restrictions to other apps running on the managed profile.
+</p>
+
+<p class="note">
+  <strong>Note:</strong> This lesson does not cover the situation where the
+  only profile on the device is the managed profile, under the enterprise's
+  control.
+</p>
+
+<h2 id="overview">Device Administration Overview</h2>
+
+<p>
+  In an Android for Work deployment, the enterprise administrator can set
+  policies to control the behavior of employees' devices and apps. The
+  enterprise administrator sets these policies with software provided by their
+  Enterprise Mobility Management (EMM) provider. The EMM software communicates
+  with a Work Policy Controller on each device. The Work Policy Controller, in
+  turn, manages the settings and behavior of the work user profile on each
+  individual’s device.
+</p>
+
+<p class="note">
+  <strong>Note:</strong> A Work Policy Controller is built on the existing
+  model used for device administration applications, as described in <a href=
+  "{@docRoot}guide/topics/admin/device-admin.html">Device Administration</a>.
+  In particular, your app needs to create a subclass of {@link
+  android.app.admin.DeviceAdminReceiver}, as described in that document.
+</p>
+
+<h3 id="managed_profiles">Managed profiles</h3>
+
+<p>
+  Users often want to use their personal devices in an enterprise setting. This
+  situation can present enterprises with a dilemma. If the user can use their
+  own device, the enterprise has to worry that confidential information (like
+  employee emails and contacts) are on a device the enterprise does not
+  control.
+</p>
+
+<p>
+  To address this situation, Android 5.0 (API level 21) allows enterprises to
+  set up a special work user profile using the Managed Profile API. This
+  user profile is called a <em>managed profile</em>, or a <em>work profile</em>
+  in the Android for Work program. If a device has a
+  managed profile for work, the profile's settings are under the control of the
+  enterprise administrator. The administrator can choose which apps are allowed
+  for that profile, and can control just what device features are available to
+  the profile.
+</p>
+
+<h2 id="create_profile">Create a Managed Profile</h2>
+
+<p>To create a managed profile on a device that already has a personal profile,
+first check that the device can support a managed profile, by seeing if the
+device supports the {@link
+android.content.pm.PackageManager#FEATURE_MANAGED_USERS FEATURE_MANAGED_USERS}
+system feature:</p>
+
+<pre>PackageManager pm = getPackageManager();
+if (!pm.hasSystemFeature(PackageManager.FEATURE_MANAGED_USERS)) {
+
+    // This device does not support native managed profiles!
+
+}</pre>
+
+<p>If the device supports managed profiles, create one by sending an intent with
+an {@link android.app.admin.DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE
+ACTION_PROVISION_MANAGED_PROFILE} action. Include the device admin package
+name as an extra.</p>
+
+<pre>Activity provisioningActivity = getActivity();
+
+// You'll need the package name for the WPC app.
+String myWPCPackageName = "com.example.myWPCApp";
+
+// Set up the provisioning intent
+Intent provisioningIntent =
+        new Intent("android.app.action.PROVISION_MANAGED_PROFILE");
+intent.putExtra(myWPCPackageName,
+        provisioningActivity.getApplicationContext().getPackageName());
+
+if (provisioningIntent.resolveActivity(provisioningActivity.getPackageManager())
+         == null) {
+
+    // No handler for intent! Can't provision this device.
+    // Show an error message and cancel.
+} else {
+
+    // REQUEST_PROVISION_MANAGED_PROFILE is defined
+    // to be a suitable request code
+    startActivityForResult(provisioningIntent,
+            REQUEST_PROVISION_MANAGED_PROFILE);
+    provisioningActivity.finish();
+}</pre>
+
+<p>The system responds to this intent by doing the following:</p>
+
+<ul>
+  <li>Verifies that the device is encrypted. If it is not, the system prompts
+  the user to encrypt the device before proceeding.
+  </li>
+
+  <li>Creates a managed profile.
+  </li>
+
+  <li>Removes non-required applications from the managed profile.
+  </li>
+
+  <li>Copies the Work Policy Controller application into the managed profile and
+    sets it as the profile owner.
+  </li>
+</ul>
+
+<p>Override {@link android.app.Activity#onActivityResult onActivityResult()} to
+see whether the provisioning was successful, as shown in the following 
+example code:</p>
+
+<pre>&#64;Override
+public void onActivityResult(int requestCode, int resultCode, Intent data) {
+
+    // Check if this is the result of the provisioning activity
+    if (requestCode == REQUEST_PROVISION_MANAGED_PROFILE) {
+
+        // If provisioning was successful, the result code is 
+        // Activity.RESULT_OK
+        if (resultCode == Activity.RESULT_OK) {
+            // Hurray! Managed profile created and provisioned!
+        } else {
+            // Boo! Provisioning failed!
+        }
+        return;
+
+    } else {
+        // This is the result of some other activity, call the superclass
+        super.onActivityResult(requestCode, resultCode, data);
+    }
+}</pre>
+
+<h3 id="after_creating_profile">After Creating the Managed Profile</h3>
+
+<p>When the profile has been provisioned, the system calls the Work Policy
+Controller app's {@link
+android.app.admin.DeviceAdminReceiver#onProfileProvisioningComplete
+DeviceAdminReceiver.onProfileProvisioningComplete()} method. Override this
+callback method to finish enabling the managed profile.</p>
+
+<p>Typically, your {@link
+android.app.admin.DeviceAdminReceiver#onProfileProvisioningComplete
+DeviceAdminReceiver.onProfileProvisioningComplete()} callback implementation
+would perform these tasks:</p>
+
+<ul>
+  <li>Verify that the device is complying with the EMM's device policies, as
+  described in <a href="#set_up_policies">Set Up Device Policies</a>
+  </li>
+
+  <li>Enable any system applications that the administrator chooses to make
+  available within the managed profile, using {@link
+  android.app.admin.DevicePolicyManager#enableSystemApp
+  DevicePolicyManager.enableSystemApp()}   </li>
+
+  <li>If the device uses Google Play for Work, add the Google account
+  to the managed profile with {@link android.accounts.AccountManager#addAccount
+  AccountManager.addAccount()}, so administrators can install
+  applications to the device
+  </li>
+</ul>
+
+<p>Once you have completed these tasks, call the device policy manager's
+{@link android.app.admin.DevicePolicyManager#setProfileEnabled
+setProfileEnabled()} method to activate the managed profile:</p>
+
+
+<pre>// Get the device policy manager
+DevicePolicyManager myDevicePolicyMgr =
+        (DevicePolicyManager) getSystemService(Context.DEVICE_POLICY_SERVICE);
+
+ComponentName componentName = myDeviceAdminReceiver.getComponentName(this);
+
+// Set the name for the newly created managed profile.
+myDevicePolicyMgr.setProfileName(componentName, "My New Managed Profile");
+
+// ...and enable the profile
+manager.setProfileEnabled(componentName);</pre>
+
+<h2 id="set_up_policies">Set Up Device Policies</h2>
+
+<p>
+  The Work Policy Controller app is responsible for applying the enterprise's
+  device policies. For example, a particular enterprise might require that all
+  devices become locked after a certain number of failed attempts to enter the
+  device password. The controller app queries the EMM to find out what
+  the current policies are, then uses the <a href=
+  "{@docRoot}guide/topics/admin/device-admin.html">Device Administration</a>
+  API to apply those policies.
+</p>
+
+<p>For information on how to apply device policies, see the 
+<a href="{@docRoot}guide/topics/admin/device-admin.html#policies">Device
+Administration</a> guide.</p>
+
+
+<h2 id="apply_restrictions">Apply App Restrictions</h2>
+
+<p>Enterprise environments may require that approved apps implement apps
+implement security or feature restrictions. App developers must implement these
+restrictions and declare them for use by enterprise administrators, as described
+in <a href="{@docRoot}training/enterprise/app-restrictions.html">Implementing
+App Restrictions</a>. The Work Policy Controller receives restriction changes
+from the enterprise administrator, and forwards those restriction changes to the
+apps.</p>
+
+<p>For example, a particular news app might have a restriction setting that
+controls whether the app is allowed to download videos over a cellular
+network. When the EMM wants to disable cellular downloads, it sends a
+notification to the controller app. The controller app, in turn,
+notifies the news app that the restriction setting has changed.</p>
+
+<p class="note"><strong>Note:</strong> This document covers how the Work Policy
+Controller app changes the restriction settings for the other apps on the
+managed profile. Details on how the Work Policy Controller app communicates with
+the EMM are out of scope for this document.</p>
+
+<p>To change an app's restrictions, call the {@link
+android.app.admin.DevicePolicyManager#setApplicationRestrictions
+DevicePolicyManager.setApplicationRestrictions()} method. This method is passed
+three parameters: the controller app's {@link
+android.app.admin.DeviceAdminReceiver}, the package name of the app whose
+restrictions are being changed, and a {@link android.os.Bundle Bundle} that
+contains the restrictions you want to set.</p>
+
+<p>For example, suppose there's an app on the managed profile with the package
+name <code>"com.example.newsfetcher"</code>. This app has a single boolean
+restriction that can be configured, with the key
+<code>"downloadByCellular"</code>. If this restriction is set to
+<code>false</code>, the newsfetcher app is not allowed to download data through
+a cellular network; it must use a Wi-Fi network instead.</p>
+
+<p>
+  If your Work Policy Controller app needs to turn off cellular downloads, it
+  would first fetch the device policy service object, as described above. It
+  then assembles a restrictions bundle and passes this bundle to {@link
+  android.app.admin.DevicePolicyManager#setApplicationRestrictions
+  setApplicationRestrictions()}:
+</p>
+
+<pre>// Fetch the DevicePolicyManager
+DevicePolicyManager myDevicePolicyMgr =
+        (DevicePolicyManager) thisActivity
+                .getSystemService(Context.DEVICE_POLICY_SERVICE);
+
+// Set up the restrictions bundle
+bundle restrictionsBundle = new Bundle();
+restrictionsBundle.putBoolean("downloadByCellular", false);
+
+// Pass the restrictions to the policy manager. Assume the WPC app
+// already has a DeviceAdminReceiver defined (myDeviceAdminReceiver).
+myDevicePolicyMgr.setApplicationRestrictions(
+        myDeviceAdminReceiver, "com.example.newsfetcher", restrictionsBundle);</pre>
+
+
+<p class="note"><strong>Note:</strong> The device policy service conveys the restrictions
+change to the app you name. However, it is up to that app to actually implement
+the restriction. For example, in this case, the app would be responsible for
+disabling its ability to use cellular networks for video downloads. Setting the
+restriction does not cause the system to enforce this restriction on the app.
+For more information, see <a href="{@docRoot}training/enterprise/app-
+restrictions.html">Implementing App Restrictions</a>.</p>