Introducing the RBA User Management Activities

[russ_sarbora]

The Automation team has started to build out a set of user management activities. Our end goal is to enable customers to automate their on-boarding/off-boarding processes with auditable, self-documenting workflows that save time and eliminate mistakes. The initial release in this area will be focused on managing user accounts in Active Directory, and will be in the October release. Even better, you can get an early look starting with October Preview 3!

An integrated set

This first release will include six activities that cover the most common use cases admins have for managing Active Directory user accounts. They are: Create AD User Account, Update AD User Account, Remove AD User Account, Disable AD User Account, Query AD, Reset AD User Password. There is also a matching Reset Linux User Password. The set share a common design, have complementary functionality, and share a common set of parameters. Our hope is that you will be find it very easy to mix-and-match them into consistent workflows for provisioning and de-provisioning user accounts.

The activity names are pretty self-explanatory, and the specifics on each are documented in the wiki, but let's do a quick overview here. There are a couple logical subgroupings into which the activities fall:

Group - Description	Activities
Generic - These activities offer configurable functionality for modifying AD User accounts.	Update AD User Account, Create AD User Account, Remove AD User Account
Specific - These activities do very specific task with very little configuration required.	Disable AD User Account, Reset AD User Password, Reset Linux User Password
Query - This activity provides a generic but configurable querying capability that call pull data from the AD back into your Runbook.	Query AD

The activities are configured via a common set of activity variables:

Common Activity Variables
Domain Controller	the IP of the domain controller for the Active Directory you want to manage. Currently, it must be an IP address, hostnames and domain names will not work.
Username	the sAMAccountName of the user account in question. sAMAccountName is used as the key across all of the activities.
User Data	a JSON object containing AD properties and their values For example, if you wanted to set the first name, last name, and title of a user, your User Data object would look like this: { "givenName" : "Joe", "SN" : "Testdude", "title" : "crash test dummy" }

Not all the activities will use all of these, and some have parameters that are specific to them. But you can assume that the User variable on Create AD User means the same thing and accepts the same format as the User variable on Disable AD User. We've also tried to make the activities behave intuitively and consistently across the set. For example, The Create activity will fail if it finds an existing account, and conversely, the Update activity will fail if it doesn't find an existing account. All the activities will attempt to pass through any error messages returned from the AD.

How about an example? Syncing An AD User

Now that you know a little about these activities, lets assemble them into a useful workflow. What if you wanted to make your ServiceNow instance the single system of record for User account data? You'd need your Active Directory to stay updated with any changes. So a runbook that could push changes to an SNC User record down to the Active Directory would be pretty sweet. Let's build one.

Step 1 : Create a new workflow - In your instance, open the workflow editor and click the New button at the top left. The New Workflow dialog will open. Name it "Sync AD User" and select the "global" table.

Click submit and you'll be taken to a blank workflow editing canvas.

Step 2 : Configure the Workflow Inputs - Open the workflow inputs edit screen and click the New button to create a new input variable. Call it "user" and make it a reference to the sys_user table.

Our example workflow is going to assume that you have SNC LDAP integration plugin enabled, and have configured an LDAP server that your user accounts will be pushed to. Now, the AD User management activities themselves are not dependent on the LDAP integration plugin, but it will make this example workflow much easier. If you don't have the plugin enabled, you can still make the example work. You'll just need to provide the domain controller's IP to workflow, either by hardcoding it, adding another workflow input, or using some script to look it up from your CMDB.

Save the "user" variable and close the Workflow Inputs screen. You'll be back at your blank workflow canvas. Look at the Activities menu on the right of the canvas. You should see a folder for Runbook - Active Directory. Open that folder and you'll see the new user management activities.

Step 3 : Add the Update AD User Activity -Since we're creating a workflow that will update the AD with user account changes, let's start by adding the Update AD User Account activity. When you drop the activity onto the canvas, it will open the Activity Properties screen. Here's how we'll fill out this screen:

Property	Value
Name	any name will work, but make it something logical like "update user account"
Stage	leave blank
Domain Controller	remember, this is the IP address of the domain controller for the AD we want to update. This is where the LDAP integration plugin will help us out. The plugin adds a reference to the LDAP server that the User's account is linked to. So we can just dot-walk our way to the info we need with the following expression: ${workflow.inputs.u_user.ldap_server.server_url}
Username	We're also going to assume that our SNC Username matches our AD sAMAccountName : ${workflow.inputs.u_user.user_name}
User Data	Let's set the first name, last name, and title of our user. Again, we can pull the data we need from the user record. But this time we need the expression evaluations to end up in a JSON object. This should do it: { "givenName" : "${workflow.inputs.u_user.first_name}", "SN" : "${workflow.inputs.u_user.last_name}", "title" : "${workflow.inputs.u_user.last_name}" }

Save your changes and return to the Workflow canvas. Your workflow should now look like this

At this point, our workflow takes an SNC User record as input, and updates the First Name, Last Name, and Title of the corresponding Active Directory account. Not bad, but what if the user account doesn't already exist in the AD? Our workflow will fail unless someone manually creates the AD account ahead of time. Let's fix that.

Step 4 : Add the Create AD User Account Activity - Grab a Create AD User activity and drag it onto the transition line between Start and Update. Here's how you fill out the properties screen for this activity.

Property	Value
Name	create user account
Stage	leave blank
Domain Controller	${workflow.inputs.u_user.ldap_server.server_url}
OU	Enter a valid LDAP Organization Unit. In the real world, it wil be something like "OU=Users,OU=HQ,OU=Locations,OU=Managed Objects", but for our example, let's just use "cn=Users"
Username	${workflow.inputs.u_user.user_name}
User Data	We can just leave this blank. We'll use the Update activity to push the interesting data.

Save the property settings and return to the Workflow canvas. The Success outcome of the Create activity will be hooked up to the Update activity.

Now our workflow will create a barebones AD account, and then update that account with a more complete set of information pulled from the SNC User record. We're not really any better off than before, now the Runbook can't handle the case where the user accounts already exists.

Step 5 : Retrieve some data with Query AD - The answer to this problem is to add some conditional branching. We'll use the Query AD activity to retrieve any matches to our User, then use an If activity to branch the flow based on whether the results of that query are empty or not. First lets add the Query.

Drag a Query AD activity onto the transition line between Start and Create AD User Account. For the Query AD properties use the following:

Property	Value
Name	search for existing account
Domain Controller	${workflow.inputs.u_user.ldap_server.server_url}
Properties	the list of AD property values that you want to pull back. It needs to be a comma-separated list like: "givenName, SN, title". If you leave this parameter blank, then all properties will be retrieved. In our case, we're more interested in if any entries are returned than what the values of their properties are, so let's just leave it blank.
Search Filter	This is a LDAP filter string that defines what you're searching for. You can use any valid LDAP filter criteria. We're looking for AD Users whose sAMAccountName matches our input records user_name property: (samaccountname=${workflow.inputs.u_user.user_name})

Save the activity properties and return to the workflow canvas. At this point, your workflow should look like this.

Step 6 : Branching with an If - The Query AD activity will return its results as a JSON string and put them in the workflow scratchpad (as workflow.scratchpad.queryAD). This JSON string will always be an array of objects. Each object corresponds to an AD entry that matched our query. Our workflow should branch depending on whether that array is empty or not. We can use a standard If activity for that. Drag an If from the Conditionals folder of the Activities menu onto the transition between Query and Create. Name it "if account exists" and then check the Advanced checkbox. That will open a script box where you can enter the following script:

var queryResults=new JSON().decode(workflow.scratchpad.queryAD);
answer = ( queryResults.length>0 ? 'yes' : 'no' );

What is this script doing? You can check the docs for the If activity for more details, but basically we just need to return a "yes" or "no" in the answer variable, which will correspond to the Yes and No outcomes of our activity. Line 1 converts the Query AD results from a JSON string into a Javascript array called queryResults. Line 2 checks the length of that array, if its more than 0, a match to our account was found, so we set our answer to yes, otherwise its a no.

Save those properties, and return to the canvas. Now drag a transition from the Yes outcome of our If to the Update activity, and from the No outcome to the Create activity.

One last minor detail, we have not handled any of the Failure outcomes. "Of course not", you say, "my code never fails." Nonetheless, in a real Runbook, you would probably want to take some alternate action on a failure. Since this is an example, I'll buy what you're selling and we can just connect all of the Failures to the End activity.

This final version of the runbook will query to see if an account already exists, create one if necessary, and then update the AD with our complete User Data set.

Step 7 : Use a business rule to launch the runbook - Remember, our original intent for this example was to push changes made to SNC User records to the AD. So we need our Runbook to run anytime a User record changes, In other words, we need a business rule. Open the Business Rules module in System Definition app and click the New button. Here's the settings you'll need.

Property	Value
Name	Sync AD User
Table	User [sys_user]
Active	checked
When	after
Insert	checked
Checked	checked
Script	var wf=new Workflow(); var id=wf.getWorkflowFromName('Sync AD User'); wf.startFlow(id,null,'Sync AD User', {u_user:current.sys_id});

I'm not going to get into how business rules work. Long-story short, after a User record is updated or inserted the script will run. The script is launching our Runbook, passing it the User record in the workflow input variable u_user.

Whoohoo! We're finished. To try it out, go to the Users module of the User Administration application in your instance. Add a new User, making sure you assign them to an LDAP server.