SIMS 7 - System Manager

Background

A number of partners have asked for access to the System Manager functionality.  All of our system manager functionality has been in COM Dlls which were never published for reasons of security.  Some of the functionality is still concealed for the same reasons; however we have had the need to provide limited access to the security system to allow external management of SIMS users for SLG and SIMS.

Key Factors

New functionality makes it possible to make an existing SIMS ‘person’ a SIMS or SLG user.

The new functionality will only allow the creation of users linked to NT accounts.

User’s granting access to SIMS/SLG via these routines need to be members of the specific security group – Third Party User Management.

Why only allow the creation of a login for a Windows User.

 

The major reason for the creation of these interfaces did not require access for non AD users.  This also allowed us to avoid the question of password management.  Allowing the setting or returning a password for SIMS SQL users to and from an external system would require significant additional work to ensure an appropriate degree of data protection.

 

Versions of SIMS Required.

 

This code will be included in the Autumn 2010 release of SIMS subject to passing appropriate testing.  These calls will not work on earlier versions.

 

Functionality

 

TPADProvisioning - AddProvisioningService

 

Definition

 

bool TPADProvisioning.AddProvisioningService ( ID as GUID (not null) , ClientID as GUID (not null), URL as String (not null), Name as String (not null), Description as String (not null) )

 

c# Example

 

using (TPADProvisioning adProvServ = new TPADProvisioning())
{
    Guid ProvisioninServiceid = Guid.NewGuid(); Guid ClientId = Guid.NewGuid();
    bool createOK = adProvServ.AddProvisioningService(ProvisioninServiceid, ClientId, "https://whatever.com",  // max 255 chars                    
        "SERVICE",   // max 10 chars                    
        "Provisioning Service"); // max 100 chars  
    if (!createOK)
    {
        foreach (ValidationError error in securityGroup.ValidationMessages) { richTextBoxDisplayInfo.Text += error.Message + "\n"; }
    }
}

 

Description

 

This method is used to register a provisioning service with a specific SIMS DB, and is required by the SLG components as they use the Client GUID and Entity GUID to uniquely identify a user in the system (the values are stored in the directory for this purpose). This method provides an alternative to manually generating, downloading and installing SIMS ADP.

 

Please note that this method doesn’t do any of the provisioning, it simply defines a service and use of this function would need to be accompanied with some form of alternative provisioning service. 

 

Parameters

 

Name

Description

Notes

ID

The provisioning service GUID

GUID

ClientID

The SIMS instance GUID which

uniquely identifies the SIMS DB

 

GUID

URL

The URL of the provisioning

service, will appear in SIMS

 

Max 255

Name

The name of the provisioning

service, will appear in SIMS

 

Max 10

Description

The description of the provisioning

service, will appear in SIMS

 

Max 100

 

 

Returns

 

Boolean

 

True

If Successful

False

If an error occurs

 

 

Please note that if the call fails, the set of validation errors should be parsed to see why.

 

Exceptions

 

It is also possible that an exception will occur if a fault occurs.  This too should be catered for.

 

 

 

Warnings

 

1.  Unless ADPS/SIMS Learning Gateway is licensed, users will not see this information via SIMS .Net.
2. ESS recommends the use of ADPS to provision external systems with SIMS ‘people’.  The use of SLG without ADPS is likely to cause issues!  Fundamentally ADPS can be customised to manage AD via a third party system.  This mechanism still maintains the change management requirement of provisioning.
3. Hence use with Caution! Consultancy is recommended before work begins in this area!  www.sims.co.uk/partners for details.

 

 

TPADProvisioning - GetProvisioningServices

 

Definition

 

adProvServ.GetProvisioningServices()

 

The method takes no parameters

 

c# Example

 

 

 

using (TPADProvisioning adProvServ = new TPADProvisioning())
{  
    richTextBoxDisplayInfo.Text = adProvServ.GetProvisioningServices();  
    richTextBoxDisplayInfo.Refresh();
}

 

Description

 

This method is used to enumerate the currently registered provisioning services within a specific SIMS DB.

 

Return Values

 

This returns a string:

 

 

<ProvisioningServices>
  <ProvisioningService>
    <ProvisioningServiceId>c0c715e1-24c1-4375-aeee-ed9e35e40b84</ProvisioningServiceId>
    <ClientId>14c76acb-1870-4098-b3e3-ff741814edb0</ClientId>
    <ServerUrl>http://192.168.0.000:1101/ClientInterface.asmx</ServerUrl>
    <Name>Provisioning Service</Name>
    <ServiceCode>wedge</ServiceCode>
  </ProvisioningService>
</ProvisioningServices>

 

Containing the list of provisioning services in SIMS.

 

Warnings

 

See above, this method simply lists the existing services and is relatively harmless.

 

<TPSecurityGroup – GetAvailableSecurityGroups>

 

Definition

 

This function will get the set of security (System) groups in the SIMS database.

 

c# Example

 

TPSecurityGroup securityGroup = new TPSecurityGroup();
availableSecurityGroups = securityGroup.GetAvailableSecurityGroups();      
richTextBoxDisplayInfo.Text = availableSecurityGroups;

 

Description

 

The function is typically suited to the population of a list of available security groups.

 

Parameters

 

None

 

Returns

 

XML as follows:

 

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<SecurityGroups>
  <SecurityGroup>
    <BaseGroupID>473</BaseGroupID>
    <ExternalID>e7d35cb9-e19f-43d9-9318-d444d1a1ca66</ExternalID>
    <Code>AdminAss</Code>
    <Description>Administration Assistant</Description>
    <ActiveState>Active</ActiveState>
    <Status>System</Status>
  </SecurityGroup>
</SecurityGroups>

 

There are no validation errors returned by this call.

 

Exceptions

 

It is also possible that an exception will occur if a fault occurs.  This too should be catered for.

 

A typical exception is thrown when the user has no rights to use the call.

 

<TPUser – CreateUser>

 

Definition

 

This call allows an existing person in SIMS identified by their external ID to be made a SIMS or SLG user.  The difference between the 2 is that an SLG user does not have a SIMS login name.

 

Please note that it requires that a SIMS user name is of the form DOMAIN\User in order to ensure that Windows provides the password management and authentication.

 

 

 

c# Example for the creation of an SLG user

 

TPUser user = new TPUser(); bool createUser = user.CreateUser(PersonExternalID, UserName1, false);
richTextBoxDisplayInfo.Text = " Ran Create a Non sims User\n";
if (!createUser)
{
    foreach (ValidationError error in user.ValidationMessages)
    {
        richTextBoxDisplayInfo.Text += error.Message + "\n";
    }
}
richTextBoxDisplayInfo.Refresh();

 

c# Example for the creation of a SIMS user

 

TPUser user = new TPUser(); bool createUser = user.CreateUser(PersonExternalID, UserName1, true);
richTextBoxDisplayInfo.Text = " Ran Create a SIMS User\n";
if (!createUser)
{
    foreach (ValidationError error in user.ValidationMessages)
    { richTextBoxDisplayInfo.Text += error.Message + "\n"; }
}
richTextBoxDisplayInfo.Refresh();

 

Parameters

 

Name

Description

Notes

PersonExternalID

The GUID for the SIMS person

GUID

User Name

DOMAIN\User if provided.

String (20 chars max)

SIMSUser

True for SIMS users, false for SLG users

Bool

Returns

 

Boolean

 

True

If Successful

False

If an error occurs

Please note that if the call fails, the set of validation errors should be parsed to see why.

 

Exceptions

 

It is also possible that an exception will occur if a fault occurs.  This too should be catered for.

 

 

TPSecurityGroup – CreateSecurityGroupMembership()

 

Definition

 

This function allows the create a membership for security groups.

 

c# Example

 

TPSecurityGroup SecurityGroup = new TPSecurityGroup();
richTextBoxDisplayInfo.Text = " Ran CreateSecurityGroupMembership()\n";
bool addMembership = securityGroup.CreateSecurityGroupMembership(PersonExternalID, SecGroupID, DateTime.Now, DateTime.Now.AddYears(2));
if (!addMembership)
{
    foreach (ValidationError error in securityGroup.ValidationMessages)
    { richTextBoxDisplayInfo.Text += error.Message + "\n"; }
}

 

Description

 

Particular issues surround the group ‘System Manager’ because members of this group have elevated database rights where members are made SIMS backup operators.

 

Parameters

 

Name

Description

Notes

PersonExternalID

The external ID of the SIMS user

GUID – Required

GroupExternalID

The external ID of the security group required.

GUID – Required

Start

Date which membership should start – time is ignored.

DateTime – Required

End

Date which membership should end – time is ignored.

DateTime

Optional parameter

Returns

 

Boolean

 

True

If Successful

False

If an error occurs

Please note that if the call fails, the set of validation errors should be parsed to see why.

 

Exceptions

 

It is also possible that an exception will occur if a fault occurs.  This too should be catered for.

 

 

 

Warnings

 

1. Please note that this call may well appear to work for non ‘Users’, however unless the person is made a user, they won’t be able to log in even if they are made members of the group.

 

 

<TPSecurityGroup – RevokeSecurityGroupMembership()

 

Definition

 

This function is used to terminate access rights

 

c# Example

 

TPSecurityGroup SecurityGroup = new TPSecurityGroup();
richTextBoxDisplayInfo.Text = " Ran RevokeSecurityGroupMembership()\n";
bool revokeMembership = securityGroup.RevokeSecurityGroupMembership(PersonExternalID, SecGroupID, DateTime.Now);

if (!revokeMembership)
{
    foreach (ValidationError error in securityGroup.ValidationMessages)
    {
        richTextBoxDisplayInfo.Text += error.Message + "\n";
    }
}

 

Description

 

This call allows the removal of access rights for a user from a given date. 

 

Parameters

 

Name

Description

Notes

PersonExternalID

The external ID of the SIMS user

GUID – Required

GroupExternalID

The external ID of the security group required.

GUID – Required

Termination Date

Date which membership should END – time is ignored.

DateTime – Required

Returns

 

Boolean

 

True

If Successful

False

If an error occurs

Please note that if the call fails, the set of validation errors should be parsed to see why.

 

Exceptions

 

It is also possible that an exception will occur if a fault occurs.  This too should be catered for.

 

 

 

 

 

 

 

<TPUser – RemoveUser()

 

Definition

 

This function is used to terminate all access rights by removing their login.

 

c# Example

 

TPUser user = new TPUser();
richTextBoxDisplayInfo.Text = " Remove User\n";
bool removeUser = user.RemoveUser(PersonExternalID);
if (!removeUser)
{
    foreach (ValidationError error in securityGroup.ValidationMessages)
    {
        richTextBoxDisplayInfo.Text += error.Message + "\n";
    }
}

 

 

 

Description

 

This call will either delete the user or make them inactive.  It is not possible to remove user records that are linked to other artefacts.  This works in a similar way to System Manager.

 

Parameters

 

Name

Description

Notes

PersonExternalID

The external ID of the SIMS user

GUID – Required

Returns

 

Boolean

 

True

If Successful

False

If an error occurs

Please note that if the call fails, the set of validation errors should be parsed to see why.

 

Exceptions

 

It is also possible that an exception will occur if a fault occurs.  This too should be catered for.

 

Warnings

 

1. There are some issues with System manager removing NT users because of assumptions that it makes.  For example if a user has other access rights then removing their login would not be correct.
2. The user’s login to SQL will remain but their rights to the specific SIMS database will be revoked.
3. The username will be removed from db_users.

 

 

 

 

<TPSecurityGroup – GetSecurityGroupMemberships()

 

Definition

 

This function will return the set of Security group memberships for the dates specified.

 

Options

 

GetSecurityGroupMemberships(<Person External ID>, <Start Date>,< End Date>)

 

GetSecurityGroupMemberships(<Person External ID>, <Start Date>)

 

GetSecurityGroupMemberships(<Person External ID>)      

 

c# Example

 

TPUser user = new TPuser();
richTextBoxDisplayInfo.Text = user.GetSecurityGroupMemberships(PersonExternalID);
richTextBoxDisplayInfo.Refresh(); 

 

Description

 

This call allows the removal of access rights for a user from a given date. 

 

Parameters

 

Name

Description

Notes

PersonExternalID

The external ID of the SIMS user

GUID – Required

From

Start Date for memberships – ignores time element

DateTime Optional

Default ‘Now’

To

Start Date for memberships – ignores time element

DateTime Optional

Default ‘31/12/2070’

Returns

 

XML as follows

 

 

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<SecurityGroupMemberships>
  <SecurityGroupMembership>
    <ExternalID>e7d35cb9-e19f-43d9-9318-d444d1a1ca66</ExternalID>
    <Code>AdminAss</Code>
    <Description>Administration Assistant</Description>
    <startdate>2010-10-12T00:00:00</startdate>
    <enddate>2012-10-12T23:59:00</enddate>
  </SecurityGroupMembership>
</SecurityGroupMemberships>

 

Exceptions

 

It is also possible that an exception will occur if a fault occurs.  This too should be catered for.

 

<TPUser –UpdateUser()

 

Definition

 

This function is used to terminate access rights

 

c# Example

 

TPUser user = new TPUser();
if (!user.UpdateUser(PersonExternalID, UserName2))
{
    foreach (ValidationError error in securityGroup.ValidationMessages)
    {
        richTextBoxDisplayInfo.Text += error.Message + "\n";
    }
}

 

Description

 

This call allows the replacement of the NT user name for a SIMS User.  This preserves the access rights for the user.  A typical usage for this would be the change of user name on marriage or by deed poll.

 

Parameters

 

Name

Description

Notes

PersonExternalID

The external ID of the SIMS user

GUID – Required

New NT User Name

DOMAIN\User the new login name for the user.

String (20) required

Returns

 

Boolean

 

True

If Successful

False

If an error occurs

Please note that if the call fails, the set of validation errors should be parsed to see why.

 

Exceptions

 

It is also possible that an exception will occur if a fault occurs.  This too should be catered for.

 

Warnings

 

1. This can only be invoked for domains where the user name can be resolved.  Local names Machine\User can be used too and are suitable for test.