In this article by Miguel Oliveira, author of the book Microsoft System Center Orchestrator 2012 R2 Essentials, we will learn to get started on the creational process. We will be able to driven on how to address and connect all the pieces together in order to successfully create a Runbook.

(For more resources related to this topic, see here.)

Runbook for Active Directory User Account Provisioning

Now, for this Runbook, we've been challenged by our HR department to come out with a solution for them to be able to create new user accounts for recently joined employees. The request was specifically drawn with the target for them (HR) to be able to:

• Provide the first and last name
• Provide the department name
• Get that user added to the proper department group and get all the information of the user
• Send the newly created account to the IT department to provide a machine, a phone, and an e-mail address

With these requirements at the back of our heads, let's see which activities we need to get into our Runbook. I'll place these in steps for this example, so it's easy to follow:

1. Data input: So, we definitely need an activity to allow the HR to feed the information into the Runbook. For this, we can use the Initialize Data activity (Runbook control category), or we could work along with a monitored file and read the data from a line, or even from a SharePoint list. But to keep it simple for now, let's use the Initialize Data.
2. Data processing: In here, the idea would be to retrieve the Department given by the HR and process it to retrieve the group (the Get Group activity from the Active Directory category) and include our user (the Add User To Group activity from the Active Directory category) into the group we've retrieved; but in between, we'll need to create the user account (Create User activity from the Active Directory category), and generate a password (the Generate Random Text activity from the Utilities category).
3. Data output: At the very end of all this, send an e-mail (the Send Email activity from the Email category) back to HR with the account information and status of its creation and inform our IT department (for security reasons) too about the account that has been created. We're also going to closely watch for errors with a few activities that will show us whether an error occurs.

Let's see the look of this Runbook from a structured point (and actually almost how it's going to look in the end) and we'll detail the activities and options within them step by step from there. Here's the aspect of the Runbook structured with the activities properly linked between them allowing the data bus to flow and transport the published data from the beginning to the end:

As described in the steps, we start with an Initialize Data activity in which we're going to request some inputs from the person executing the Runbook.

To create a user, we'll need his First Name and Last Name and also the Department. For that, we'll fill in the following information in the Fetch User Details activity seen in the previous screenshot.

For the sake of avoiding errors, the HR department should have a proper list of departments that we know will translate into a proper group in the upcoming activities.

After filling the information, the processing of the information begins and with it, our automation process that will find the group for that department, create our user account, set a password, change password on the first login, add the user to the group, and enable the account.

For that, we'll start with the Get Group activity in which we'll fill in the following:

Set up the proper configuration in the Get Group Properties window for the Active Directory Domain in which you'll want this to execute, and in the Filters options, set to filter Sam Account Name of the group as the Department filled by the HR department.

Now we'll set another prerequisite to create the account—the password! For this, we'll get the Generate Random Text activity and set it with the following parameters:

These values should be set to accordingly accommodate your existing security policy and minimum password requirements for your domain.

These previous activities are all we need to have the necessary values to proceed with the account creation by using the Create User activity. These should be the parameters filled in.

All of these parameters are actually being retrieved from the Published Data from the last activities. As the list is long, we'll detail them here for your better understanding. Everything that's between {} is Published Data:

• Common Name: {First Name from "Fetch User Details"} {Last Name from "Fetch User Details"}
• Department: {Display Name from "Get Group"}
• Display Name: {First Name from "Fetch User Details"} {Last Name from "Fetch User Details"}
• First Name: {First Name from "Fetch User Details"}
• Last Name: {Last Name from "Fetch User Details"}
• Password: {Random text from "Generate Random Text"}
• User Must Change Password: True
• SAM Account Name: {First Name from "Fetch User Details"}.{Last Name from "Fetch User Details"}
• User Principal Name: {First Name from "Fetch User Details"}.{Last Name from "Fetch User Details"}@test.local
• Email: {First Name from "Fetch User Details"}.{Last Name from "Fetch User Details"}@test.com
• Manager: {Managed By from "Get Group"}

As said previously, most of the data comes from the Published Data and we've created subscriptions in all these fields to retrieve it. The only two fields that have data different from Published Data are the User Must Change Password, User Principal Name (UPN), and Email. The User Must Change Password is a Boolean field that will display only Yes or No, and in the UPN and e-mail we've added the domain information (@test.local and @test.com) to the Published Data.

Depending on the Create User activity's output, it will trigger a different activity. For now, let's assume that the activity returns a success on the execution, this will make the Runbook follow the smart link that goes on with the Get User activity.

The Get User activity will retrieve all the information concerning the newly created user account that will be useful for the next activities down the line.

In order to retrieve the proper information, we'll need to configure the following in the Filters area within the activity:

You'll need to add a filter, selecting Sam Account Name and Relation as Equals for Value under the subscribed data from Sam Account Name that comes out of the Create User activity.

From here, we'll link with the activity that Add User to Group (here renamed to Add User to Department) and within that activity we're going to specify the group and the user so the activity can add the user into the group. It should look exactly like the screenshot that follows:

We'll once again assume that everything's running as expected and prepare our next activity that is to enable user account and for this one, we'll use the Enable User activity.

The configuration of the activity can be seen in the next screenshot:

Once again, we'll get the information out of the Published Data and feed it into the activity. After this activity is completed, we're going to log the execution and information output into the platform with the Send Platform Event activity so we can see any necessary information available from the execution.

Here is a sample of the configuration for the message output:

To get the Details text box expanded this way, right-click on it and select Expand… from the menu, then you can format and include the data that you feel is more important for you to see it.

Then we'll send an e-mail for the HR team with the account creation details so they can communicate to the newly arrived employee and another e-mail for the IT department only with the account name and the department (plus the group name) for security reasons.

Here are the samples of these two activities, starting with the HR e-mail:

Let's go point by point on this configuration sample.

In the Details section, we've settled the following:

• Subject: Account {Sam Account Name from "Get User"} Created
• Recipients: to: hr.dept@test.com
• Message: The message description is given in the following screenshot:

  

Message option that consists of choosing the Priority of the message (high, normal, or low), and set the necessary SMTP authentication parameters (account, password, and domain) so you can send the message through your e-mail service.

If you have an application e-mail service relay, you can leave the SMTP authentication without any configuration.

In connect Connect option, you'll find the place to configure the e-mail address that you want the user to see and the SMTP connection (server, port, and SSL) through which you'll send your messages.

Now our Send Email IT activity will be more or less the same, with the exception for the destination and the message itself. It should be something a little more or less like the following screenshot:

By now you've got the idea and you're pumped to create new Runbooks, but we still have to do some error control on some of these tasks; although they're chained, if one fails, everything fails. So for this Runbook, we'll create error control on two tasks that if we observe well, are more or less the only two that can fail!

One is the Create User Account activity, which can fail due to the user account existing or by some issue with privileges on its creation. The other is Add User To Department that might fail to add the user into the group for some reason.

So for this, we'll create two notification activities called Send Event and Log Message that we'll rename to User Account Error and Group Error respectively.

If we look into the User Account Error activity, we'll set something more or less like the following screenshot:

A quick explanation of the settings is as follows:

• Computer: This is the computer to which Windows Event Viewer we're going to write the event into. In this case, we'll concentrate over our Management Server, but you might have a logging server for this.
• Message: The message gets logged into the windows event viewer. Here, we can subscribe for the error data coming out of the last activity executed.
• Severity: This is usually an Error. You can set Information or Warning if you are deploying these activities to keep a track on each given step.

So for our Group Error Properties the philosophy will be the same.

Now that we are all set, we'll need to work our smart links so that they can direct the Runbook execution flow into the following activity depending on the previous activity output (success or error).

In the end, your Runbook should look a little bit more like this:

That's it for the Runbook for Active Directory User Account Provisioning. We'll now speed up a little bit more on the other Runbooks as you'll have a much clearer understanding after this first sample.

Summary

We've seen one of the Runbook samples these Runbooks should serve as the base for real case scenarios in the environment and help us in the creativity process and also to better understand the configurations necessary on each activity in order to proceed successfully.

Resources for Article:

Further resources on this subject:

• Unpacking System Center 2012 Orchestrator [article]
• Working with VMware Infrastructure [article]
• Unboxing Docker [article]