To see the full details, you can click on the screen image.

Lost your password?

Lost your password?

Lost your password?

The Active Directory Web Service is the component of ZIAgent AD which is responsible for directly interacting with Active Directory. This document explains each of the methods of this web-service in detail.

RenameAccount

Purpose

Used to change the name of an pre-existing account. This is most commonly used to accomodate situations where account names are based on a user’s first and/or last name.

Parameters

• OldCN: The container name of the existing account. Example: Michael.Shea
• NewCN: The desired container name. Example: Mike.Shea
• NewDisplayName: The desired display name. Example: Shea, Mike

Actions Taken

• Sets CN to new value. Example: Changes Michael.Shea to Mike.Shea
• Sets property userPrincipalName. Example: Mike.Shea@visualsi.com
• Sets property sAMAccountName. Example: Changes Michael.Shea to Mike.Shea
• Sets property displayName.

Return Value

• On success: Returns "SUCCESS:IDENTITY:LDAP://…."
• On fail: Returns "FAILURE:…

SyncAccount

Purpose

Used to create the desired account if it does not already exist, or, if the account already exists, move to the proper location (OU).

Parameters

• OULDAP: The complete LDAP of the OU where the account should be created or moved to. Example: LDAP://OU=Developers,OU=Employees,DC=visualsi,DC=com
• CN: The container name of the account to be created or moved. Example: Mike.Shea
• DisplayName: The desired display name.
• MustChangePassword: Indicates if this user will be forced to change their password on next login. Example: TRUE
• PasswordNeverExpires: Indicates if this user’s password never expires. Example: FALSE
• Password: The desired password if this is a new account. This value must conform to the password policy in effect on the domain controller. Example: MyPassw0rd

Actions Taken

• If the specified account already exists in the specified OU, no action is taken.
• If the specified account already exists somewhere other than the specified OU, it will be moved to the proper OU.
• If the specified account does not exist, it will be created in the specified OU.
  • Sets CN to specified value.
  • Sets property userPrincipalName. Example: Mike.Shea@visualsi.com
  • Sets property sAMAccountName. Example: Changes Michael.Shea to Mike.Shea
  • Sets property displayName. Example: Shea, Mike
  • Sets the password on the new account.
  • Disables the account.
  • Sets the Password Never Expires flag on the account.
  • Sets the User Must Change Password flag on the account.

Return Value

• On success: Returns "SUCCESS:IDENTITY:LDAP://…."
• On fail: Returns "FAILURE:…

SyncAccountHomeDir

Purpose

To create, update, or move a home directory.

Parameters

• AccountLDAP: The complete LDAP of the account whose home directory is to be effected. Example: LDAP://CN=Mike.Shea,OU=Developers,OU=Employees,DC=visualsi,DC=com
• HomeDirTemplatePath: The path to the directory where any default files/folders exist which need to be added to this home directory. Example: MyServerHomeDirectoryTemplatesEmployee
• HomeDirPath: The path to the directory where the home directory should be located. Example: MyServerHomeDirectoriesEmployees
• HomeDirName: The name of the home directory. Example: MikeShea
• HomeDrive: The mapped drive letter to the home directory. Example: H:
• MoveHomeDir: Specifies if the home directory should be moved to the specified location. Example: TRUE
• ResetPermissionsOnExistingDir: Specifies if permissions should be reset on the home directory if it already exists. Example: FALSE

Actions Taken

• Checks to verify the specified account exists. If it does not, no further action is taken.
• If the specified account exists, retrieves the current homeDirectory property.
• If the homeDirectory property already had a value, and MoveHomeDir is set to TRUE, then attempt to copy the existing home directory (including its contents) to the new location. The original home directory and its contents are left intact in their original location.
• If the homeDirectory property already had a value, and MoveHomeDir is set to FALSE, then create the home directory in the location specified by the homeDirectory property if the home directory does not already exist there.
• If the homeDirectory property did not have a value, then create the home directory in the specified location if it does not already exist. Any files/folders in the HomeDirTemplatePath will be copied into the home directory if it was just created.

Return Value

• On success: Returns "SUCCESS:IDENTITY:MyServerHomeDirectoriesEmployeesMikeShea"
• On fail: Returns "FAILURE:…

UpdateAccount

Purpose

To update a set of pre-defined properties of an existing account.

Parameters

• AccountLDAP: The complete LDAP of the account to update. Example: LDAP://CN=Mike.Shea,OU=Developers,OU=Employees,DC=visualsi,DC=com
• EnableAccount: Enables/disables the account. Example: TRUE
• Description: Sets the Description property.
• FirstName: Sets the givenName property. Example: Mike
• LastName: Sets the sn property. Example: Shea
• MiddleInitial: Sets the initials property. Example: C
• Email: Sets the mail property. Example: mike.shea@visualsi.com
• HomePhone: Sets the homephone property. Example: 215.493.8210
• MobilePhone: Sets the mobile property. Example: 215.493.8210
• StreetAddress: Sets the streetAddress property. Example: 1105 Taylorsville Road
• POBox: Sets the postOfficeBox property. Example: 398
• City: Sets the l property. Example: Washington Crossing
• State: Sets the st property. Example: NJ
• PostalCode: Sets the postalCode property. Example: 18977
• EmployeeID: Sets the employeeID property. Example: 1234
• Company: Sets the company property. Example: Visual Software
• Department: Sets the department property. Example: Development
• Title: Sets the title property. Example: Developer
• OfficePhone: Sets the telephoneNumber property. Example: 215.493.8210
• Manager: Sets the manager property. Must be the CN of this user’s manager’s account. Example: Robert.Hutchison

Actions Taken

• Sets each property described in Parameters to the specified value.
• To ignore a property and not set its value to anything, pass in the value "NONE" for that property.
• To clear a property’s value, pass in an empty string for that property.

Return Value

• On success: Returns "SUCCESS:IDENTITY:LDAP://…."
• On fail: Returns "FAILURE:…

UpdateAccountProperty

Purpose

To update a specific property on an existing account.

Parameters

• AccountLDAP: The complete LDAP of the account to update. Example: LDAP://CN=Mike.Shea,OU=Developers,OU=Employees,DC=visualsi,DC=com
• PropertyName: The name of the property to update. Example: mail
• PropertyValue: The value to assign to the specified property. Example: mike.shea@visualsi.com

Actions Taken

• Assigns the specified value to the specified property.
• To ignore a property and not set its value to anything, pass in the value "NONE" for that property.
• To clear a property’s value, pass in an empty string for that property.
• In addition to the standard list of active directory properties, the following "special" values may be passed in using the PropertyName parameter:
  • AccountAvailability: Enables/disables an account. Acceptable values are "TRUE" and "FALSE".
  • SetPassword: Assigns a new password to the account. The value must meet the domain password policy.
  • MustChangePassword: Determines if the user must change their password on next login. Acceptable values are "TRUE" and "FALSE".
  • PasswordExpires: Determines if the account password expires. Acceptable values are "TRUE" and "FALSE".
  • SetManager: Associates a manager’s ad account with this account. Value must be a valid CN.
  • UserCannotChangePwd: Determines if the user cannot change their password. Acceptable values are "TRUE" and "FALSE".

Return Value

• On success: Returns "SUCCESS"
• On fail: Returns "FAILURE:…

SyncAccountToGroup

Purpose

To assign a pre-existing account to a pre-existing security group.

Parameters

• AccountLDAP: The complete LDAP of the account to update. Example: LDAP://CN=Mike.Shea,OU=Developers,OU=Employees,DC=visualsi,DC=com
• GroupLDAP: The complete LDAP of the security group to add the account to. Example: LDAP://CN=Developers,OU=Employees,DC=visualsi,DC=com

Actions Taken

• If the account or security group do not exist, no action is taken.
• If the account and the security group exist and the account is not already a member of the group, the account is added to the group.

Return Value

• On success: Returns "SUCCESS:IDENTITY:LDAP://…."
• On fail: Returns "FAILURE:…

RemoveAccountFromGroups

Purpose

To remove an account from one or more security groups.

Parameters

• AccountLDAP: The complete LDAP of the account to update. Example: LDAP://CN=Mike.Shea,OU=Developers,OU=Employees,DC=visualsi,DC=com
• GroupLDAP: The complete LDAP of the security group to remove the account from. An empty string is also an acceptable value. Example: LDAP://CN=Developers,OU=Employees,DC=visualsi,DC=com

Actions Taken

• If a GroupLDAP is not specified, the account will be removed from all of its current security groups.
• If a GroupLDAP is specified, the account will be removed from only that security group.

Return Value

• On success: Returns "SUCCESS"
• On fail: Returns "FAILURE:…

SyncGroupToHomeDir

Purpose

To allow a security group permission to access a home directory.

Parameters

• GroupLDAP: The complete LDAP of the security group. Example: LDAP://CN=Developers,OU=Employees,DC=visualsi,DC=com
• HomeDirPath: The path to the home directory. Example: MyServerHomeDirectoriesEmployeesMikeShea

Actions Taken

• If the group and home directory do not exist no action is taken.
• If the group and home directory exist, the group is assigned permission to access the home directory.

Return Value

• On success: Returns "SUCCESS"
• On fail: Returns "FAILURE:…

RemoveGroupFromHomeDir

Purpose

To remove a security group’s permission from a home directory.

Parameters

• GroupLDAP: The complete LDAP of the security group. Example: LDAP://CN=Developers,OU=Employees,DC=visualsi,DC=com
• HomeDirPath: The path to the home directory. Example: MyServerHomeDirectoriesEmployeesMikeShea

Actions Taken

• If the group and home directory do not exist no action is taken.
• If the group does not currently have permission on the home directory no action is taken.
• If the group and home directory exist, and the group has permission on the home directory, the group is removed from the home directory.

Return Value

• On success: Returns "SUCCESS"
• On fail: Returns "FAILURE:…

SyncOU

Purpose

To create or update an organizational unit (OU).

Parameters

• ParentLDAP: The complete LDAP of the OU which contains the OU being created or updated. Example: LDAP://OU=Employees,DC=visualsi,DC=com
• OU: The name of the oganizational unit to create or update. Example: Developers
• Description: The description of the organizational unit to create or update.

Actions Taken

• If the OU does not exist in the OU specified in ParentLDAP, it will be created.
• If the OU already exists in the specified ParentLDAP, its description will be updated.

Return Value

• On success: Returns "SUCCESS:IDENTITY:LDAP://…."
• On fail: Returns "FAILURE:…

SyncGroup

Purpose

To create or update a security group.

Parameters

• OULDAP: The complete LDAP of the OU in which this security group should exist. Example: LDAP://OU=Developers,OU=Employees,DC=visualsi,DC=com
• CN: The name of the security group to be created or updated. Example: Developers
• Description: The description of the security group.
• GroupType: The type of security group to create or update. Acceptable values are "GlobalDistribution", "GlobalSecurity", "UniversalDistribution", "UniversalSecurity". If no type is specified, "GlobalSecurity" is assumed.

Actions Taken

• If the group does not already exist in the specified OU, it will be created. The new group’s sAMAccountName property will be set to the CN, and the description property will be set to Description.
• If the group already exists in the specified OU, the description property is set.

Return Value

• On success: Returns "SUCCESS:IDENTITY:LDAP://…."
• On fail: Returns "FAILURE:…

DiscoverAccounts

Purpose

To discover information about pre-existing active directory accounts in order to syncronize them with SIF data and prevent duplicate accounts from being created.

Parameters

• ObjectName: The name of the SIF object that discovered accounts should be associated with. Example: StudentPersonal
• OULDAP: The LDAP in which to search active directory for accounts. Example: LDAP://OU=Employees,DC=visualsi,DC=com
• LocalIdProperty: The name of the active directory property which uniquely identifies accounts. This property should contain a value which exists in SIF. Example: employeeID
• SearchChildren: Indicates if the specified OU should be searched for accounts, or if this OU and all of its child OU’s should be searched. Example: TRUE

Actions Taken

• For each account found, a row is inserted to the table AD_DiscoveredAccounts in the ZIAgent database. The data inserted contains information identifying the account, including the SIF object name it is associated with, its LDAP, unique id, CN, OU, Home Directory, and Home Directory Drive.
• If SearchChildren is TRUE, searches the specified OU and all child OUs for accounts. Otherwise, searches only the specified OU.

Return Value

• On success: Returns "SUCCESS"
• On fail: Returns "FAILURE:…

A “zone” in SIF is a logical place or container where two or more agents can share data, isolated from data in any other zone. There can be many zones hosted on a typical Zone Integration Server and one agent may be registered in more than one zone concurrently (but to be useful at all it must be registered in at least one zone).

Zone Architecture

To understand where zones will be needed in an architecture, the needs and capabilities of the subscribing applications that will be used must be properly considered.

The reason why this is necessary is that, on occasion (when initializing, at end-of-year rollover and if they the want to re-sync) , subscribers will make a “request all” for certain object types. What they will get in return are all records of that type in the zone.

• Is this application allowed to see all the information returned? For example, if this application was a library system installed at a school and the information returned to it contained information from other schools, then the answer would be “no”. One school should only receive information for students from that school.

It has been a common practice to create a zone for each Student Management System (or SIS (US), or MIS (UK)); sometimes this works well , other times it doesn’t. Ideally, it should probably be more like: create a zone at the lowest level where there will be a subscribing SIF application.

Zone Architecture Examples

The following sections give some examples of SIF zone architectures that might be appropriate, depending on where student information is managed and where it is needed by subscribing applications.

United Kingdom Example

In the UK, data is typically managed in Management Information Systems (MIS) that are installed and run from individual schools. The Zone Integration Servers may reside at the school or may be centrally hosted and the subscribing applications may run locally from the schools, from a local authority or may be centrally hosted from a Regional Broadband Consortium (RBC).

In the UK, when a learner reaches age 14, he or she may begin to attend more than one school during the course of a day, causing his or her records to be managed in more than one of these MIS systems. It shouldn’t be assumed that the SIF RefIds from any of these MIS systems are synchronized, so it should also be assumed that if a learner attends two different schools, his or her school records will look like those from two different people.

NOTE: technically, the same thing will happen for special education learners who attend more than one school – their records will be maintained in more than one MIS.

(click image to open in separate window)

In this example, three schools each have their own independent zone (they could be hosted on the same Zone Integration Server) containing information provided by the school’s MIS. The subscribing application, also installed at the school, gets its information from the zone through its SIF agent. Because of the way the ZIS manages zones, it is guaranteed that information from one zone will never be mixed with that from another zone.

UK Example – Shared Applications

The above example is simple, but not all applications are installed at schools – many are hosted either at a Local Authority or at an RBC and shared by several schools.

This presents a problem. One of the most basic rules in SIF is that in a given zone, there may be only a single provider for each object.  This makes sense since a provider is defined as the agent who, by default, receives requests for a given object when a subscriber agent makes a request and doesn’t specify where to send the request (it is sent to the provider agent).

So, what you can’t do is to have all of the MIS (SIS) agents be providers in a common zone. But, there are alternatives:

• Multi-zoned agents: these are agents that register in more than one zone. For subscribing applications, writing one of these agents is somewhat difficult; for publishers it is very difficult. These agents must be able to keep track of many sets of RefId values, one for each school and if a learner appears in more than one school, it gets even more complex.
• Managed Virtual Zones (MVZ): when Visual Software entered the UK market, it realized that a problem existed with currently available facilities using SIF as implemented with multi-zoned agents. To address these problems, it invented Managed Virtual Zones and created the Envoy product to implement it. With this architecture, the application agents do not need to be written with the complex multi-zone logic – all of the complexities are centralized in one place and can be tested independently and verified before other agents are connected.

The following is a picture of how applications would be connected using a MVZ architecture and Envoy:

(click image to open in separate window)

In this example, the subscriber in the combined zone would not need to know any details about who is providing what object or learners that go to two different schools – the details would be “ironed out” and the combined community would appear as if it was being maintained by a single MIS (SIS). For more information on Envoy and MVZ, see Managed Virtual Zones.

This is an overview of of the Visual Software Active Directory SIF agent rule set for ZIAgent, its current capabilities and how it works with ZIAgent.  The VSI Active Directory agent is a plug-in to the ZIAgent SIF agent runtime.  If a school has the ZIAgent runtime, an Active Directory rule set is available for download.

Current Capabilities

The AD agent is capable of managing most aspects of an active directory schema, including:

• Creating / updating organizational units (OU’s).
• Creating / updating security groups.
• Creating / updating user accounts.
• Creating / updating home directories.

How Does This Plug-In Work?

ZIAgent is a configurable SIF agent.  We make it available in two versions:  a designer and a runtime version.  Once an agent is designed (using the designer version), it can be exported and it becomes portable.  This is useful for upgrading, since most of the time the configuration does not need to change from one SIF version to the next – all that is involved in the upgrade is <export from one version of the "agent shell" and import into the next>.  The second version is the ZIAgent runtime version.  On this one, we lowered the cost as much as possible and made the rule sets freely downloadable after that.

Structurally, the SIF agent runs under Windows Server IIS as a web site.  It installs via a MSI file and has a database that contains some configuration information and staged data received from the zone(s) the agent is registered in. This agent also employs a IIS-hosted web-service which is used for the actual interaction between the agent and active directory. This web-service is installed using a seperate MSI.

SIF Objects Supported

The default configuration of the AD agent includes support for these objects:

US 2.0r1

Subscriptions

• LEAInfo
• SchoolInfo
• TermInfo
• SchoolCourseInfo
• SectionInfo
• StudentPersonal
• StudentContact
• StudentSchoolEnrollment
• StudentSectionEnrollment
• StaffPersonal
• StaffAssignment
• EmployeePersonal
• EmployeeAssignment

Provisions

• Authentication

UK 1.1

Subscriptions

• LAInfo
• SchoolInfo
• TermInfo
• SchoolGroup
• SchoolGroupType
• LearnerPersonal
• ContactPersonal
• LearnerContact
• LearnerSchoolEnrolment
• LearnerGroupEnrolment
• WorkforcePersonal

Provisions

• Identity

Availability

Presently, this SIF agent rule set is available for the US 2.0r1 and UK 1.1 versions of the SIF specification as a downloadable plug-in to the ZIAgent Runtime SIF agent.

Lost your password?

Lost your password?

The topics covered are:

• Events, Requests, and Responses
• Push and Pull Modes
• Error Handling
• Extended Elements
• Providers and Subscribers
• Zones
• Automated Zone Splitting