Modify User Service Plans

This is an interactive task for modifying a user's licensed service plans.

Playbook Files

This playbook was built for PPA version 3.0.x

plugins:
  ppa: ^9.2
  ppa_tools: ^10.3
  hashicorp_vault: ^7.1
  microsoft_graph: ^5.0


set:
  # These are default values that get updated by the task.
  plans_to_enable:
    first: null
    last: null
    all: []
    total: 0
  plans_to_disable:
    first: null
    last: null
    all: []
    total: 0


steps:

  - name: Greeting
    actions:

      - ppa.ui.output_markdown:
          doc: >
            {{ globals.icons.windows.full }}


            ### Office 365 - Modify User's Service Plans


            Use this task to modify a user's licensed service plans in Office 365.


            You will need to:


            - Pick an Office 365 user

            - Select a licence

            - Choose whether to enable & or disable service plans

      - ppa.ui.input_accept:
          text: Start


  - name: Get Secrets
    actions:

      - hashicorp_vault.key_value.read_secret_keys:
          secret: office_365
          keys:
            - name: tenant_id
            - name: client_id
            - name: client_secret
              sensitive: true
          reason: Getting Office 365 details
          create_missing: true
        save: graph_client


  - name: Select User & Licence
    actions:

      - microsoft_graph.users.get_all:
        load:
          client: graph_client
        save: users

      - microsoft_graph.users.select_one:
          text: Select User
        load:
          users: users
        save: selected_user

      - microsoft_graph.subscriptions.get_for_user:
        load:
          user_principal_name: selected_user.user_principal_name
          client: graph_client
        save: subscriptions

      - ppa.ui.output_error:
          text: The selected user does not have any currently assigned licences.
        when: subscriptions == []

      - ppa.ui.output_error:
          text: Task cancelled, no service plans will be modified.
        when: subscriptions == []

      - exit:
          exit_code: 0
        when: subscriptions == []

      - microsoft_graph.subscriptions.select_one:
          text: Select a Licence
        load:
          subscriptions: subscriptions
        save: selected_subscription

      - ppa_tools.dictionaries.filter_from_list:
          filters:
            - key: applies_to
              type: not_equal
              value: user
        load:
          dictionaries: selected_subscription.service_plans
        save: user_service_plans

      - count:
        load:
          item: user_service_plans
        save: total_service_plan_count


  - name: Get Enabled Service Plans
    actions:

      - ppa.ui.output_progress:
          text: Getting user's service plans for the selected licence...
          element_id: get_service_plans

      - microsoft_graph.service_plans.get_enabled_for_user:
          user_only: true
        load:
          part_number: selected_subscription.part_number
          user_principal_name: selected_user.user_principal_name
          client: graph_client
        save: currently_enabled_plans

      - microsoft_graph.service_plans.get_disabled_for_user:
          user_only: true
        load:
          part_number: selected_subscription.part_number
          user_principal_name: selected_user.user_principal_name
          client: graph_client
        save: currently_disabled_plans

      - ppa_tools.dictionaries.create:
        load:
          Enabled: currently_enabled_plans
          Disabled: currently_disabled_plans
        save: table_tabs

      - ppa.ui.output_progress:
          text: Got user's service plans for the selected licence
          percent: 100
          element_id: get_service_plans

      - microsoft_graph.service_plans.display_tabbed:
          text: Enabled & Disabled Service Plans
        load:
          tabs: table_tabs

      - ppa.ui.output_info:
          text: The user has no disabled plans.
        when: currently_disabled_plans == []

      - ppa.ui.output_info:
          text: The user has no enabled plans.
        when: currently_enabled_plans == []

      - ppa.ui.input_accept:
          text: Next


  - name: Choose Service Plan Operations
    while:
      name: selection_confirmed
      value: false
    actions:

      - ppa.ui.input_checklist:
          text: Select Operation(s)
          options:
            - Enable Service Plans
            - Disable Service Plans
        save: operations

      - ppa.ui.input_confirm:
          text: No operations were selected, is this correct?
        save: cancel
        when: operations == []

      - ppa.ui.output_error:
          text: Please select the operation(s) again.
        when: operations == [] and not cancel

      - ppa.ui.output_error:
          text: Task cancelled, no service plans will be modified.
        when: operations == [] and cancel

      - exit:
          exit_code: 0
        when: operations == [] and cancel

      - set:
          name: selection_confirmed
          value: true
        when: operations != []


  - name: Skip Select Enable Plans If No Disabled Plans
    when: >
      "Enable Service Plans" in operations and currently_disabled_plans == []
    actions:

      - ppa.ui.output_info:
          text: There are no currently disabled plans to enable, this step will be skipped.

      - ppa.ui.input_accept:
          text: OK


  - name: Select Service Plans To Enable
    when: >
      "Enable Service Plans" in operations and currently_disabled_plans != []
    while:
      name: enable_confirmed
      value: false
    actions:

      - microsoft_graph.service_plans.select:
          text: Select Service Plans to Enable
        load:
          service_plans: currently_disabled_plans
        save: plans_to_enable

      - microsoft_graph.service_plans.display:
          text: Plans to Enable
        load:
          service_plans: plans_to_enable.all
        when: plans_to_enable.total > 0

      - ppa.ui.output_error:
          text: You chose not to enable any plans.
        when: plans_to_enable.total == 0

      - ppa.ui.input_confirm:
          text: Is this correct?
        save: confirm

      - ppa.ui.output_error:
          text: Please select the plans to enable again.
        when: not confirm

      - set:
          name: enable_confirmed
          value: true
        when: confirm


  - name: Skip Select Disable Plans If No Enabled Plans
    when: >
      "Disable Service Plans" in operations and currently_enabled_plans == []
    actions:

      - ppa.ui.output_info:
          text: There are no currently enabled plans to disable, this step will be skipped.

      - ppa.ui.input_accept:
          text: OK


  - name: Select Service Plans To Disable
    when: >
      "Disable Service Plans" in operations and currently_enabled_plans != []
    while:
      name: disable_confirmed
      value: false
    actions:

      - microsoft_graph.service_plans.select:
          text: Select Service Plans to Disable
        load:
          service_plans: currently_enabled_plans
        save: plans_to_disable

      - microsoft_graph.service_plans.display:
          text: Plans to Disable
        load:
          service_plans: plans_to_disable.all
        when: plans_to_disable.total > 0

      - ppa.ui.output_error:
          text: You chose not to disable any plans.
        when: plans_to_disable.total == 0

      - ppa.ui.input_confirm:
          text: Is this correct?
        save: confirm

      - ppa.ui.output_error:
          text: Please select the plans to disable again.
        when: not confirm

      - set:
          name: disable_confirmed
          value: true
        when: confirm


  - name: Exit Early If No Changes
    when: plans_to_disable.total == 0 and plans_to_enable.total == 0
    actions:

      - ppa.ui.output_info:
          text: No plans were enabled or disabled, the task will be cancelled.

      - exit:
          exit_code: 0


  - name: Process Enabled & Disabled Plan IDs
    actions:

      - ppa_tools.dictionaries.get_key_values:
          key: id
        load:
          dictionaries: currently_enabled_plans
        save: currently_enabled_ids

      - ppa_tools.dictionaries.get_key_values:
          key: id
        load:
          dictionaries: currently_disabled_plans
        save: currently_disabled_ids

      - ppa_tools.dictionaries.get_key_values:
          key: id
        load:
          dictionaries: plans_to_enable.all
        save: ids_to_enable

      - ppa_tools.dictionaries.get_key_values:
          key: id
        load:
          dictionaries: plans_to_disable.all
        save: ids_to_disable


  - name: Build Service Plan Change List
    actions:

      # Get currently disabled plans the user **chose not to enable**.
      - eval:
          expression: >
            [plan_id for plan_id in currently_disabled_ids if plan_id not in ids_to_enable]
        save: keep_disabled

      # Merge it with the list of plans the user **chose to disable**.
      - ppa_tools.lists.combine:
        load:
          first: ids_to_disable
          second: keep_disabled
        save: disabled_plan_ids

      # Get currently enabled plans the user **chose not to disable**.
      - eval:
          expression: >
            [plan_id for plan_id in currently_enabled_ids if plan_id not in ids_to_disable]
        save: keep_enabled

      # Merge it with the list of plans the user **chose to enable**.
      - ppa_tools.lists.combine:
        load:
          first: ids_to_enable
          second: keep_enabled
        save: enabled_plan_ids

      - eval:
          expression: >
            [plan for plan in user_service_plans if plan["id"] in disabled_plan_ids]
        save: disabled_plans

      - count:
        load:
          item: disabled_plans
        save: disabled_plan_count

      - count:
        load:
          item: enabled_plan_ids
        save: enabled_plan_count


  - name: Change Summary
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### Change Summary


            **User:** {{ selected_user.user_principal_name }}


            **New Enabled Plans:** {{ plans_to_enable.total }}


            **New Disabled Plans:** {{ plans_to_disable.total }}


            Once updated the user will have access to **{{ total_service_plan_count - disabled_plan_count }}** of **{{ total_service_plan_count }}** service plans.

      - ppa.ui.input_confirm:
          text: Update service plans?
        save: update

      - ppa.ui.output_error:
          text: Task cancelled, no service plans will be modified.
        when: not update

      - exit:
          exit_code: 0
        when: not update


  - name: Update Licence Service Plans
    actions:

      - ppa.ui.output_progress:
          text: Updating user licence with {{ enabled_plan_count }} enabled & {{ disabled_plan_count }} disabled plans...
          percent: null
          element_id: update_licence

      - microsoft_graph.subscriptions.assign_to_user:
        load:
          disabled_plans: disabled_plans
          sku_id: selected_subscription.sku_id
          user_principal_name: selected_user.user_principal_name
          client: graph_client

      - ppa.ui.output_progress:
          text: Updated user licence with {{ enabled_plan_count }} enabled & {{ disabled_plan_count }} disabled plans
          percent: 100
          element_id: update_licence

Running this Playbook

Click download playbook
Import the playbook on the Playbooks page in PPA
Build the playbook from the Edit & Build tab
Run the playbook from the Preview & Deploy tab

Integrations

PPA User Interface
Hashicorp Vault Key-Value engine
Microsoft Graph Users & Subscriptions

Required Vault Details

Office 365

Azure Tenant ID
Client ID (the ID of the app registration in Azure)
Client Secret

The Office 365 credentials require the following permissions:

Directory.Read.All
User.ReadWrite.All

Vault Configuration Wizard

The first time you run a task built from this playbook, PPA will check the required Vault details exist.

If they don't exist, PPA will ask you to supply the details at the start of the task.

Below you can see a user providing details the first time they run an Active Directory task.

vault-config-wizard

Once the details are added to Vault, the task won't ask for them again.

If you don't know the required details, ask an administrator to run the task or configure Vault manually.

What the Task Does

Once started, this task allows the operator to:

Pick an Office 365 user
Select a subscription
Choose whether to enable & or disable service plans

See our other playbooks

Get PPA for free!

Start automating your estate with a free 30 day trial today. No signup required!

Get PPA Express

Documentation

Installation Guide
See how easy it is to get started with our installation guide
Playbooks
View our task writing reference guide
Plugins
See how to integrate with different systems using our plugins reference guide.