Provisioning of Empirum Packages as Services

Provision services based on Empirum Packages

The imported services based on Empirum packages can be provided in the Self Service Protal or manually assigned.

Purpose

The Empirum Provisioning Data Provider allows the creation of software services which are provisioned via workflows by leveraging the connected Empirum software deployment system.

The software services can be installed, repaired (re-installed) and returned (un-installation) automatically.

Prerequisites

The Empirum location is configured in the Empirum Inventory Data Provider.
Services are created and refined based on the automated import or via the "Create Service" action. The configuration is described here.

Used components

The provisioning of the services uses two workflows.

Provisioning - Install Software with Empirum. This is the provisioning workflow selected in the Service. It required the correct Empirum location information based on the Empirum Provisioning data provider and the Empirum package ID. Both information are added automatically when creating the services with the Empirum Provisioning data provider.
Change Management WF - Install Software with Empirum. This workflow connects to the Empirum API based on the settings in the Empirum Inventory Data Provider and controls the software deployment tasks and status updates.

Simplified Service Provisioning Flow

Provisioning states

The following states are possible and will set the order and change status based on the provisioning feedback.

Orders are updated by the sub processes according to the Service Catalog standards. Once all required approvals are provided the progress moves to the Provisioning.

Provisioning pending: The Change Management WF - Install Software with Empirum is initiated. It sends the install/reinstall/uninstall call to Empirum.
- Empirum creates a dedicated configuration group for each computer
  - Configuration Groups/Service Management/Domain/OU/computer name is used as structure. See the Empirum Help for Details.
  - The selected target computer and the Empirum software package associated with the ordered service is placed in the group.
  - The computer will start the process at the next polling if the UEM Agent is not outside the configured maintenance window.
    - Repair will create a so called "Reinstall" group temporarily. Empirum resolves this group once the reinstallation is performed successfully.
      
      Note: Reinstall will not show an UEM Agent user interface. It is performed with the next UEM Agent polling.
    - Returning a service will set the distribution command in Empirum to Uninstall. Once the software is uninstalled successfully the software gets removed from the group. If the software was the only assigned software in the group the whole group gets removed in Empirum.
- The workflow polls Empirum for the status of the task by default every 60 seconds.
- Depending on the state in Empirum the workflow updates the change state, order state and creates tasks in case of errors.
  - If the installation was successful or already performed by Empirum - Order state is updated from approved to provisioned. After the user accepts the fulfillment it is set to fulfilled.
  - If the service is repaired and Empirum reinstalled the software successfully the Order state is updated from approved to provisioned. After the user accepts the fulfillment it is set to fulfilled.
  - If the service is returned and Empirum uninstalled the software successfully the Order state is updated from approved to provisioned. After the user accepts the fulfillment it is set to fulfilled.

Tasks created on errors

If one of the workflows stops with an error the system automatically creates a task which can be reviewed in the Service Catalog App. The tasks can be reviewed in Collaboration -> Tasks as member of the user role "Empirum Connector". The task also contains the last error message. for troubleshooting.

If Empirum returns that the computer is currently in a reinstall process (a reinstall group is present for this computer in Empirum) the workflow retries for 24 hours before creating a ticket.

If the error is based on a software installation issue within Empirum the workflow creates specific tasks depending on the reason.

Content of the ticket:

To solve the Problem try following options:

If the Service was incorrectly configured, fix the configuration and re-run "Empirum Service Provisioning Task" by closing this task with reason "Solved".
Repair / Reinstall the requested Software manually on the target and close this task with reason "Obsolete".
Abort the Provisioning of this Service and close this task with reason "Aborted".

Additional notes and hints

Allow users to postpone installations

By default software packages are assigned with the distribution command "Install and Update" in Empirum. This can be changed by editing the distribution commands in Empirum on the group level (Service Management or a certain domain). New groups will inherit the distribution command. This allows as an example to let the user postpone the installation several days. Managing Service Management assignment groups require the Empirum role EMP_M_SUPERADMIN. Read the best practice for software distribution for more details.

Maximum number of failed installations in Empirum

Empirum provides a functionality to stop the installation after a configured amount of retries. This prevents that users are disturbed infinitely when a software package has an error or a certain condition on the computer results in failed installations. Once the maximum number is reached the UEM Agent will not try to install the software again. If this is configured the provisioning will get the error state after the maximum failed retries is reached and not with the first failed installation. See the Empirum help for details of the Agent Template configuration. Once the package is fixed the ticket can be closed with the reason "Solved" to start a reinstall (also installs the package if not already installed). If the package cannot be fixed the task should be closed with the reason "Aborted" to remove the assignment.

Troubleshooting

Review the order state

The orders can be reviewed in the Service Catalog App.

Review the tasks which are created on errors

The tasks can be reviewed in Service Catalog -> Collaboration -> Tasks

Error when ordering multiple software services in one order

When ordering several software services in one order in rare circumstances the provisioning might stop with an error and a task is created. Usually closing the task with the solution directly solved will rerun the provisioning and all software services are correctly processed.

Resuming the workflow in the Administration does not solve the issue.

Using service bundles which are based on Software Classes in Empirum do not have this issue and might be more convenient for users.

Detailed Provisioning Use Cases

Provisioning Activity	Error / Precondition	Task	Task Closing Reason	Provisioning	Order Status
Order single service or bundle	Misconfiguration of Empirum Provisioning Data Provider or other workflow error	Reconfigure Empirum Provisioning	Solved or Directly Solved	The workflow will run the whole provisioning again.	Pending until the Task is closed. Workflow, Booking, and Change are pending until the Task is closed.
Order single service or bundle		Reconfigure Empirum Provisioning	Any other closing reason	The workflow will do a Rollback (1).	Pending until the Task is closed. Workflow, Booking, and Change are pending until the Task is closed.
Order single service or bundle	Rollback(1) is failed	Reconfigure Empirum Provisioning	Solved or Directly Solved	The workflow will run the rollback again.	Pending until the Task is closed.
Order single service or bundle	Rollback(1) is failed	Reconfigure Empirum Provisioning	Any other closing reason	The rollback(1) will be skipped.	Pending until the Task is closed.
Order single service or bundle	Software installation error	Automated software installation for service 'XYZ' failed.	Solved or Directly Solved (by fixing the package)	Software of service will be assigned in Empirum with “Reinstall” to force a retry after the maximum number of errors was reached.	Pending until install successful.
			Obsolete	The software of the service will not be removed from the Empirum assignment. No further provisioning activities will be performed by the workflow.	Provisioned
			Aborted	The software of the service will be removed from the Empirum assignment Bundles: if any software package from the Bundle was installed, it will remain on the target device.	Provisioning Failed
Order single service or bundle	Software uninstallation/repair error	Automated software uninstallation/repair for service 'XYZ' failed.	Solved Directly Solved (by fixing the package)	The workflow will run the whole provisioning again.	Pending until uninstall/repair successful.
			Obsolete	No further provisioning activities will be performed by the workflow.	Provisioned
			Aborted	Uninstallation: The assignment in Empirum will return to its previous state. Repair: The reinstall assignment in Empirum will be removed.	Provisioning Failed
Order single service	Software already assigned in Empirum	Automated software installation for service 'XYZ' failed.	Solved Directly Solved (by removing the existing assignment)	Software of service will be assigned in Empirum.	Provisioned
			Obsolete	No further provisioning activities will be performed by the workflow.	Provisioned
			Aborted	No additional assignment in Empirum	Provisioning Failed
Order single service or bundle	Software already installed by Empirum (manually or former assignment) and no assignment in Empirum present	No task created		Software of service will be assigned in Empirum. No installation required.	Provisioned
Order Bundle	Contained Service already assigned in Empirum	Automated software installation for service 'XYZ' failed.	Solved Directly Solved (by removing the existing assignment)	Software of service will be assigned in Empirum.	Provisioned
			Obsolete	No further provisioning activities will be performed by the workflow.	Provisioned
			Aborted	No assignment of the bundle in Empirum. If any software package from the Bundle was installed, it will remain on the target device.	Provisioning Failed
Order single service or bundle	Order, Booking, or Workflow is cancelled.	No task created		The workflow will do a rollback. Installation: Software of service will be removed from Empirum assignment. Installation of Bundle: if any software package from the Bundle was installed, it will remain on the target device. Uninstallation: The assignment in Empirum will return to its previous state. Repair: The reinstall assignment in Empirum will be removed.	Cancelled
Order single service or bundle	Cancellation rollback failed.	Reconfigure Empirum automation	Solved or Directly Solved	The workflow will run the cancellation rollback again.	Pending until the Task is closed.
Order single service or bundle	Cancellation rollback failed.	Reconfigure Empirum automation	Another	The cancellation rollback will be skipped.	Pending until the Task is closed.
Order single service or bundle	Reinstallation of another package is ongoing	No task created		Workflow will retry every 30 minutes the provisioning. After 24 hours of retrying “Reconfigure Empirum automation“ task will be created.	Pending

(1) Rollback actions:

Installation Rollback: The software of the service will be removed from the Empirum assignment. Bundle: if any package from the Bundle is installed, it will remain on the target device.
Uninstallation: The assignment in Empirum will return to its previous state. If the package is broken the status in Empirum will be "undefined".
Repair: The reinstall assignment in Empirum will be removed.