System Design Document Level 1 (SDD1)€¦ · All controlled documents must be controlled following the SWG Document Control Procedure, Proc-0006, located in the SWG Document Library

Tivoli Software System Design Document Level 1 (SDD1)

Online Version is the Master IBM Confidential (when filled in) Page 1 of 36

SWG - TIVOLI

Tenant Administration Application

System Design Document Level 1 (SDD1)

Document Version: 1.0

Document Revision Status: Draft

Document Date: 08/09/2012

References in content to IBM products, software, programs, services or associated technologies do not imply that they will be available in all countries in which IBM operates. Content, including any plans contained in content, may change at any time at IBM's sole discretion, based on market opportunities or other factors, and is not intended to be a commitment to future content, including product or feature availability, in any way. Statements regarding IBM's future direction or intent are subject to change or withdrawal without notice and represent goals and objectives only. Please refer to the developerWorks terms of use for more information.

1.0

Notice: The online version is the Master. Any printed versions of this document are FOR REFERENCE ONLY.

Users of this document are responsible for using the official version, and for verifying that any copies are complete and of the official version.



Document Control Information

Document Owner: Colleen McCretton – Designer/Architect

Document Author: Colleen McCretton – Designer/Architect Document Approvers:

Functional Area and Role Approver’s Name

Role > Determine as appropriate to Project (required) [name]

<Identify Specific Role who must Approve> [name]

Document Reviewers:

Functional Area and Role

(Indicate Role, such as Manager, Team Lead) Status Reviewer's Name

Functions and Roles as per Project] Required [name]

Functions and Roles as per Project Optional [name]

Summary of Changes: The Document Author/Owner is authorized to make the following types of changes to the document without requiring that the document be re-approved:

• editorial, formatting and spelling

• clarification

• document structure To request a change to this document, contact the Document Author or Owner. Changes to this document are summarized in the following table in chronological order.

Version Date Short Description

1.0 TBD Initial Version, Approved

Document Source: The location of the official version of this controlled document is described in the Project Planning Document (PPD), section 5.0 Data Management, Table 1 Project Documents.

Document Template: TPDM SDD1Template, TIV-T&F-0023, revision 4, Tivoli Document Library (QMX)

All controlled documents must be controlled following the SWG Document Control Procedure, Proc-0006, located in the SWG Document Library (QMX) database.



About this Document

The System Design Document Level 1 (SDD1) is produced as a work product (deliverable or artifact) from the TPDM Design and Write the Process in support of the Tivoli Product Development Model (TPDM).

The SDD1, or equivalent design document, is created for product and component development projects. The help text for requested information will indicate if the information is specifically applicable to only one type of development project: product or component.

The SDD1, or equivalent design document, describes the interfaces and semantics of a major subsystem of the

overall system for the product/component. The interfaces represent the “contractual obligation” between this

particular system component and the other components in the overall product/component solution. The SDD1

provides sufficient details for users (developers, ID, Test, HCI) to understand overall subsystem behavior. The

SDD1 is also intended to provide information to the Service organizations responsible for maintaining the

product/component after release.

The SDD1 provides sufficient details for users (developers, ID, Test, HCI) to understand overall subsystem

behavior. The SDD1 is also intended to provide information to the Service organizations responsible for

maintaining the product/component after release.

The SDD1 is formally reviewed by relevant parties as planned. Issues identified during the review are addressed prior to approval.

The SDD1 is approved by the appropriate authority and placed under change control after approval.



Table of Contents

1. Introduction................................................................................................................................................6

1.1 Overview .............................................................................................................................................6

1.2 Component Dependencies .................................................................................................................6

1.3 Related Release Documents ..............................................................................................................6

2. Requirements Addressed .........................................................................................................................6

2.1 Requirements......................................................................................................................................6

2.2 Personas and Scenarios.....................................................................................................................7

2.3 Main Components of the Architecture ................................................................................................7

2.4 Static Object and Data Models .........................................................................................................16

2.5 Dynamic (Runtime) Models ..............................................................................................................25

2.6 Finite State Machines (optional) .......................................................................................................28

2.7 Other .................................................................................................................................................28

3. System Structure Flows..........................................................................................................................28

3.1 Error Flows........................................................................................................................................28

3.2 Cross-Component Flows ..................................................................................................................29

3.3 Cross-Product Flows (not applicable to component design) ............................................................29

4. Other Design Considerations.................................................................................................................29

4.1 Open Source.....................................................................................................................................30

5. APIs, External Interfaces and Semantics..............................................................................................30

5.1 Command Line Support ....................................................................................................................30

5.2 Programmatic Interfaces (APIs)........................................................................................................30

5.3 External Messages ...........................................................................................................................30

5.4 User Assistance Provided.................................................................................................................30

6. Multi-Customer Implications ..................................................................................................................30

7. Compatibility, Upgrade, and Coexistence ............................................................................................30

7.1 Compatibility .....................................................................................................................................30

7.2 Upgrade ............................................................................................................................................31

7.3 Coexistence ......................................................................................................................................31

7.4 Interaction with other Tivoli Products/Components ..........................................................................31

8. Installation and Configuration................................................................................................................31

8.1 Upgrade ............................................................................................................................................31

8.2 Installation and Packaging................................................................................................................31

8.3 Configuration.....................................................................................................................................31

8.4 Post Install Configuration..................................................................................................................31

8.5 Installability .......................................................................................................................................32

9. Reliability, Availability and Serviceability (RAS) and Maintainability ................................................32

9.1 Reliability and Availability .................................................................................................................32

9.2 Serviceability.....................................................................................................................................32

9.3 Maintainability ...................................................................................................................................32

10. Accessibility.............................................................................................................................................32

11. Performance.............................................................................................................................................32

12. Security and Authentication...................................................................................................................32

12.1 Encryption/Cryptography ..................................................................................................................33

12.2 Authentication ...................................................................................................................................33

12.3 Authorization .....................................................................................................................................33

13. Usability....................................................................................................................................................33

14. Documentation ........................................................................................................................................33

15. Globalization ............................................................................................................................................33

16. Privacy ......................................................................................................................................................34

17. Educational Services ..............................................................................................................................34



18. Intellectual Property ................................................................................................................................34

19. Test and Testability .................................................................................................................................35

19.1 Development / Unit Test ...................................................................................................................35

19.2 Testability Considerations.................................................................................................................35

19.3 External Tool Dependency ...............................................................................................................35

19.4 Internal Tool Dependency.................................................................................................................35

20. Down Stream Component Design Documentation ..............................................................................35



1. Introduction

1.1 Overview

A new application ‘Tenants’ will be provided to allow managers of multi-tenant systems to add tenant records and modify existing tenants. The application will provide the ability to enter general information about the tenant including the ability to create a tenant contact and add an administrative user for the system and register the database user created for the system. The tenant record will also be statusable. Creation of a tenant record will initiate several processes within the system mentioned in this specification but detailed in other specifications.

1.2 Component Dependencies

Fine-Grain Access Control (FGAC); context switching; Delta storage; authentication.

1.3 Related Release Documents

Table 1: Related Documents Document Title Location or Link

Market Themes Document N/A

Release Content Specification TBD

Stage Delivery Plan for this release N/A

System Design Document Level 0 (SDD0/CDD) for this release

N/A

UI SDD1 Document N/A

Persona Document N/A

Related Documentation None

2. Requirements Addressed

2.1 Requirements

Req. ID ## Requirement Title

Create an application for 'landlords' to setup and administer tenants



2.2 Personas and Scenarios

Story 1 - As a 'landlord' I need to be able to add tenants. Story 2 - As a landlord I need to be able to modify and disable tenants. Story 3 - As a landlord I need a method to communicate tenant code and user id information to a new tenant. Story 4 – As a landlord I need to create a template Maximo system for my new tenant. Story 5 – As a landlord I need to allow my tenants to use their e-mail to login to the system but also provide valid values for userid and personid in a simple, easy to use fashion. Story 6 - As a tenant I need to be able to update information about my organization such as billing contacts and addresses for my contract with the landlord.

2.3 Main Components of the Architecture

Story 1 – As a ‘landlord’ I need to be able to add tenants. Tenant Administration App – ‘Landlord’ A new application titled ‘Tenants’ will be created for the ‘landlord’ to use to create and update basic tenant information. It will be located in the Administration module. This will be a ‘custom’ application for the ‘landlord’ tenant – it will be in MAXAPPS with the landlord tenant id so only the landlord will see it. It will not be granted to any groups by default in a ‘regular’ database but can be granted to the admin group in a demo database. In its first iteration it will consist of a ‘List’ tab and a ‘Tenant’ tab as illustrated below. In later iterations additional tabs may be added for other tenant configurations such as properties, MAXVARS and integration queue use.

List Tenant More Tabs Later

Tenant Description Company



The fields described above will be tied to the attributes described below. Additional attributes not shown on the screen will also be required and are specified in section 2.4. The ‘Set Password’ function will set an auto-generated password, email it to the user and set it to expire on first login. Future password expiration dates will use the standard User business logic. A ‘Landlord’ can never set a tenant’s password to a known value. They can only set and reset it to a generated value that is communicated directly to the user. The existing non-persistent attributes for setting passwords and communication template for e-mailing them should be leveraged, if possible. A new action will be introduced for resetting the password – the business logic for this process will be different than for setting the initial password and will be covered in a separate story. The use of communication templates to provide login and password information has some risk as an administrator could set up a bcc: to their own e-mail with the credentials but the assumption is that only privileged users will have access to modify communication templates so this risk is acceptable.

Field Name Tenant

Description Unique identifier for tenant

Editing Characteristics

Required, read only after save

List Tenant More Tabs Later?

Tenant: (Description)

Company:

Contact First Name: Contact Last Name:

Address:

City: State: Zip/Postal: Country:

Contact Phone: Contact e-mail:

Tenant Admin Login ID :

Tenant Database User ID :

Tenant Admin Language :

Set Password



Validation Must be unique, no spaces and use the same handler as loginid on MAXUSER.

Additional Information

Database Field TENANTREG.TENANTCODE

Field Name <None>

Description


Validation


LD enabled

Database Field TENANTREG.DESCRIPTION

Field Name Company:

Description Tenant Company


Required

Validation


Database Field TENANTREG.COMPANY

Field Name Contact First Name:

Description


Required

Validation


Same as PERSON.FIRSTNAME

Database Field TENANTREG.FIRSTNAME

Field Name Contact Last Name:

Description


Required

Validation


Same as PERSON.LASTNAME

Database Field TENANTREG.LASTNAME



Field Name Address:

Description


Validation


Sam as PERSON.ADDRESSLINE1

Database Field TENANTREG.ADDRESSLINE1

Field Name City:

Description


Validation


Same as PERSON.CITY

Database Field TENANTREG.CITY

Field Name State:

Description


Validation


Same as PERSON.STATEPROVINCE

Database Field TENANTREG.STATEPROVINCE

Field Name Zip:

Description


Validation


Same as PERSON.POSTALCODE

Database Field TENANTREG. POSTALCODE

Field Name Country:

Description


Validation




Same as PERSON.COUNTRY

Database Field TENANTREG.COUNTRY

Field Name Contact Phone:

Description


Validation


Same as PERSON.PRIMARYPHONE

Database Field TENANTREG.PRIMARYPHONE

Field Name Contact e-mail:

Description


required

Validation


Same as PERSON.PRIMARYEMAIL

Database Field TENANTREG.PRIMARYEMAIL

Field Name Tenant Admin Login ID:

Description



Validation


Also copied to MAXUSER.LOGINID, MAXUSER.USERID and PERSON.PERSONID by non-persistent, context switched process described below. 30 characters.

Database Field TENANTREG.LOGINID

Field Name Tenant Database User ID:

Description



Validation


Will be validated on initial connection to the database for context switching.

Database Field TENANTREG.DATABASEUSERID

Field Name Tenant Admin Language:



Description


Defaults to base language

Validation


The value list will be populated by the list of enabled languages on the system.

Database Field TENANTREG.TENANTLANGCODE

Story 2 - As a landlord I need to be able to modify and disable tenants. After a tenant is created it may be necessary for a ‘landlord’ to update information.

Advanced search functionality should be provided for this application. The fields for First Name, Last Name, Tenant Admin Login ID, Tenant Database User ID and Tenant Admin Language will be included.

In addition, a tenant record should be statusable. A ‘STATUS’ attribute will be added to the TENANTREG table and a field will be added to the Tenant Administration application UI on both the list and main tabs. The details for the attribute and fields are described below. There will be three possible tenant statuses to start – new, active and inactive. A new synonym domain – ‘TENANTSTATUS’ - will be required for these statuses. For this sprint the default status, configured in the database, will be ‘ACTIVE’ but in future when tenant self registration is enabled it will most likely change to ‘NEW’ or a client can change the database default to ‘NEW’. The details for this new domain are provided in section 2.4 below.

Field Name Status:

New field goes here

‘Status:’



Description Tenant Status


Required

Validation TENANTSTATUS domain


Database Field TENANTREG.STATUS

When a new tenant is added the default status will be ‘ACTIVE’. When the tenant status is ‘active’ it will initiate the creation of the tenant template and ‘delta’ storage data.

A ‘Change Status’ action and toolbar button are required to enable changing tenant statuses.

A standard ‘Change Status’ dialog will be implemented. A tenant status history table will also be needed to view historical information and capture a ‘memo’ on transactions. With this table it should be possible to workflow enable tenant approval without additional code but this should be validated.

When the tenant status is changed to inactive, the users for that tenant will not be able to log in. They will receive the standard message that you cannot login, please contact your system administrator.

In addition to changing the status of the tenant a landlord needs a method to reset a tenant administrator’s password if they have locked themselves out of the system. An action, ‘Reset Password’ will be added to the action menu. A standard confirmation dialog confirming that the password should be changed should be presented before the process is initiated to ensure a password is not accidentally reset. When the action is performed, a new password should be generated and e-mailed to the user just as it was when the tenant was initially created. The new password should also be set to expire on first login. The loginid field will be used to map between the impacted tables.

Story 3 - As a landlord I need to communicate login information to new tenants. When a new tenant is added the password for the administrative user will automatically be e-mailed to the tenant’s primary contact. For security reasons, the login information and tenant code should not be included in that same e-mail. A separate e-mail should be sent with this information. To accomplish this, a new communication template, TENANTLOGIN, will be needed. When the new tenant user is saved a message using this communication template will be sent. Details on the new communication are provided in section 2.4 below. Story 4 – As a landlord I need to create a template Maximo system for my new tenant. When a new record is saved for a tenant in addition to the administrative user being created data needs to be populated to ‘seed’ the system as if the client had run ‘maxinst’ for a ‘maximo’ database (not ‘maxdemo’) for their new system. The system will use three concepts for data storage:

• ‘system’ data which is unique in the system and will not be flagged with a tenandid column

• ‘delta storage’ data which is most often shared by tenants but can be tenant unique and only the tenant changes will be stored. For example, a maximo system comes with many ALN domains. These values will be stored once and shared by the system. If a tenant adds a value that row will be added to the table and flagged with an id only flagged for that tenantid.

• ‘template’ data is data which is most likely to be unique and modified for each tenant. When a new tenant is added all the rows flagged as template data will be copied and flagged for each tenantid. For example, there are default records in the APPLICATIONAUTH table that are needed for an administrator to log in for the first time but each tenant will have their own authorizations in the APPLICATIONAUTH table.

The specific details of these tables and how they are populated are covered later in this spec and the definitions of the data modeling are detailed in the technical specification for this project.



A method for removing tenant data and deleting a tenant is also needed and will be detailed in a later story. Story 5 – As a landlord I need to allow my tenants to use their e-mail to log in to the system but also provide valid values for userid and personid in a simple, easy to use fashion. When a new tenant registers they will provide a value they want to use as their loginid. Because the loginid attribute in the MAXUSER table is a longer, ALN field than the USERID attribute of MAXUSER and PERSONID attribute of PERSON a tenant could select a loginid value that will not be valid as a userid or personid. By default, we will copy the loginid and convert it to UPPER and try to use it as both the userid and personidIf the loginid cannot be saved, a dialog box will be launched. This dialog will display a truncated string of the loginid shortened to fit into the field. The control in which the string is displayed must be able to show all the text, by scrolling if necessary, so that the user knows what is cut off. It will give the user the option to use this value or specify something else. For example, if the tenant admin loginid was ‘[email protected]’ it would be converted to ‘[email protected]’. The dialog will appear something like this: Story 6 – As a tenant I need to be able to update information about my organization such as billing contacts and addresses for my contract with the landlord. Tenant Administration App – ‘Tenant’ Future Functionality Additional application functions Add application authorizations - how does this factor in with licenses and what is in the MAXAPPS/license file/Application tab in Security Groups to be granted Integration queues? Tenant Self Registration Web page similar to self-registration page for a tenant to self register A user/authorization similar to 'maxreg' would be needed to have access to create the data

Workflow process to notify of new tenant requests

‘Storefront’ to order services/provide payment

Initial configuration wizard – can be used for setting up a new system multi-tenant or not.

Information to 'seed' the system including Base Language ORGID SITEID ITEMSET

The tenant can access the system using the Tenant Admin Login ID value you entered. However, if the Tenant Admin Login ID is too long to be used as the USERID and PERSONID for the admin user of the tenant the truncated value shown will be used. You can modify the truncated value, but when you save it, it is read-only.

[email protected]

OK Cancel



COMPANYSET Base Currency Defalult GL Account



2.4 Static Object and Data Models

Column Changes For Table: INSERT

TENANTREG

Column Name /

Column Alias

UPPER(18)

Column Title / Remarks

ALN(80)

Max Type

UPPER (8)

Length

Scale

Nulls

Allowed

LDKEY

(Y/N)

LDKEY

Owner (Y/N)

Domain

Name

List type

SameAs

Table /

Column

Type Must

Be

Nums Only

Posi-tive

Null

w/default

Default

Value

TENANTCODE Tenant UPPER 20 N

DESCRIPTION Description ALN 200 Y Y

TENANTID Tenant ID BIGINT N

COMPANY Company ALN Y

FIRSTNAME First Name Y PERSON.FIRSTNAME

LASTNAME Last Name Y PERSON.LASTNAME

ADDRESS1 Address Y PERSON.ADDRESS1

ADDRESS2 Address Line 2

Y PERSON.ADDRESS2

ADDRESS3 Address Line 3

Y PERSON.ADDRESS3

CITY City Y PERSON.CITY

STATEPROVINCE State/Province

Y PERSON.STATEPROVINCE

POSTALCODE Zip/Postal Code

Y PERSON.POSTALCODE

COUNTRY Country Y PERSON.COUNTRY



Story 2

PRIMARYPHONE Primary Phone

Y PERSON.PRIMARYPHONE

PRIMARYEMAIL Primary e-mail

Y PERSON.PRIMARYEMAIL

TENANTLOGINID Tenant Admin Login ID

ALN 30 N MAXUSER.LOGINID

TENANTDBUSERID Tenant Database User ID

ALN 30 N MAXUSER.DATABASEUSERID

TENANTLANGCODE Tenant Admin Language Code

N PERSON.LANGCODE Maximo base language

TENANTREGID N


TENANTREG

Column Name /

Column Alias

UPPER(18)


ALN(80)

Max Type

UPPER (8)

Length

Scale

Nulls

Allowed

LDKEY

(Y/N)

LDKEY

Owner (Y/N)

Domain

Name

List type

SameAs

Table /

Column

Type Must

Be

Nums Only

Posi-tive

Null

w/default

Default

Value

STATUS Tenant Status

UPPER 12 N N N TENANTSTATUS

APPR



New TENANTSTATUS domain

Domain: TENANTSTATUS

Description: Tenant Status

Type: SYNONYM

Internal Value Value Description Default

NEW NEW New Tenants N

ACTIVE ACTIVE Active tenants Y

INACTIVE INACTIVE Inactive tenants N

New SIGOPTION Records

APP OPTIONNAME DESCRIPTION ESIGENABLED VISIBLE ALSOGRANTS

ALSOREVOKES

PREREQUISITE

TENANTREG READ Read access to Tenants 0 1 CLEAR, BOOKMARK, NEXT, PREVIOUS,

ALL

INSERT New Tenant 0 1 SAVE

SAVE Save Tenant 0 1 INSERT, DELETE


TENANTSTATUSHIST

Column Name /

Column Alias

UPPER(18)


ALN(80)

Max Type

UPPER (8)

Length

Scale

Nulls

Allowed

LDKEY

(Y/N)

LDKEY

Owner (Y/N)

Domain

Name

List type

SameAs

Table /

Column

Type Must

Be

Nums Only

Posi-tive

Null

w/default

Default

Value

STATUS Tenant Status

UPPER 12 N N N TENANTSTATUS

APPR



DELETE Delete Tenant 0 1 SAVE

CLEAR Clear Changes 1 0

NEXT Next Tenant 0 0

PREVIOUS Previous Tenant 0 0

BOOKMARK Add to Bookmarks 0 0

PWCHANGE Change Password 0 1

STATUS Change Status 0 1

SENDLOGIN Send Login Information 0 1

SEARCHMORE More Search Fields 0 1

The values for SIGOPTIONID, LANGCODE, HASLD and ROWSTAMP will be defaulted by the system.

Story 3

New Communication Template:

Template: TENANTLOGIN

Description: Template for e-mailing new tenant login details

Applies to: TENANTREG

Accessible from: ALL

All other header fields appear to be system generated.

Template Details:

To: e-mail of user determined by application <MAXUSER role>

Cc: null

Bcc: null

Send From: [email protected]

Reply To: null

Subject: Important information about your Maximo account

Message: Enclosed is your new login information.



<loginid>

<tenantcode>

To log in and change your password, follow this link:

< http://:HOSTNAME/maximo/ui/maximo>

The communication template should be active by default.

Story 4

As part of this feature, data within the standard system tables that is included in a new client data will be identified as

‘system’ – it will stay as it is today

‘master’ – it will be shared by tenants but they can add their own data in addition that will be stored as ‘delta’

‘template’ – data that will be copied for each new tenant

Below is the list of tables that have been identified as ‘master’ and ‘template’. See the technical specification and specification for the scripts that create this data for additional detail.

Master/Delta Storage Enabled Tables Template Data Tables

ACTION ACTIONGROUP

ALNDOMAIN APPDOCTYPE

CONDITION APPLICATIONAUTH

CROSSOVERDOMAIN AUTOKEY

CRONTASKDEF COMMTEMPLATE

DMCFGGROUP COMMTMPLTSENDTO

DMCFGOBJECT CONTRACTDEFAULT

DMCOLLLOOKUPRULE CONTRACTPROPERTY

DMCOLLPKGEXCEPTION CRONTASKINSTANCE

DMCOLLRELRULE CRONTASKPARAM

DMCOLLRELRULECOLS CTRLCONDITION



DMDEPENDENCY CTRLCONDPROP

LANGUAGE CTRLGROUP

MAXAPPS DEFAULTQUERY

MAXATTRIBUTE DMPACKAGEDEF

MAXATTRIBUTECFG DMPKGCFGGRPDEF

MAXCONDDETAIL DMPKGDEFSTATUS

MAXCONTROLVALUE DOCTYPES

MAXDOMAINLINK ESCALATION

MAXDYNAMICDOMLINK ESCNOTIFICATION

MAXINTOBJECT ESCREFPOINT

MAXINTOBJDETAIL GROUPUSER

MAXINTOBJCOLS GRPREASSIGNAUTH

MAXINTOBJALIAS KPIMAIN

MAXIFACEIN KPITRENDCFG

MAXIFACEOUT LONGDESCRIPTION Needs more thought – can be delta or master depending on parent

MAXHANDLER MAXENDPOINT

MAXIFACEPROC MAXENDPOINTDTL

MAXIFACECOND MAXEXTIFACEIN

MAXIFACECONTROL MAXEXTIFACEOUT

MAXPROCCOLS MAXEXTLISTVAL

MAXREPLACEPROC MAXEXTSYSCONTROL

MAXTRANSFORMPROC MAXEXTSYSTEM

MAXDOMAIN MAXIFACEINVOKE

MAXLABELS MAXIFACEOUTCNTL

MAXLOOKUPMAP MAXINTLISTENER

MAXMENU MAXINTPOLICY

MAXMESSAGES MAXINTPOLICYPARAM



MAXMODULES MAXGROUP

MAXOBJECT MAXLAUNCHENTRY

MAXOBJECTCFG MAXLECONTEXT

MAXPRESENTATION MAXROLE

MAXPROP MAXUSER

MAXPROPVALUE PERSON

MAXRELATIONSHIP PERSONANCESTOR

MAXSYSINDEXES PORTLET

MAXSYSKEYS QUERY

MAXTABLE REPORT

MAXTABLECFG REPORTAPPAUTH

MAXTABLEDOMAIN REPORTLABEL

MAXVARS REPORTLOOKUP

MAXVARTYPE REPORTOSAUTH

MAXVIEW SECURITYRESTRICT

MAXVIEWCFG SKDACTION

MAXVIEWCOLUMN SKDDATAGROUP

MAXVIEWCOLUMNCFG SKDOBJECT

MAXSERVSECURITY SKDOBJECTMGR

MXCOLLAB SKDPROPERTY

MXCOLLABREF SKDPROPERTYMAP

NUMERICDOMAIN SKDRESOBJECT

NUMRANGEDOMAIN SKDRESOURCEVIEW

PALETTEITEM TLOAMPRMDFLT

PROPERTYASSOC TLOAMSWCATALOG

RESULTSETCOLS WFACTION

SIGOPTFLAG WFAPPTOOLBAR

SIGOPTION WFASSIGNMENT



SYNONYMDOMAIN WFCONDITION

WFINTERACTION

WFNODE

WFNOTIFICATION

WFPROCESS

WFREVISION

WFSTART

WFSTOP

WFTASK

Three nonpersistent fields will be presented in the application. The provided values will replace the specified values in template data.

Field Name Default Group for New Users

Description Group to which Maximo automatically assigns new users, including those who self register. This group determines a user's initial security privileges.


Defaults to MAXDEFLTREG. Required at UI level.

Validation


When creating template data, MAXDEFLTREG will be replaced with the provided value. Same as MAXGROUP.GROUPNAME.

Database Field Nonpersistent (NEWUSERGROUP)

Field Name Group for All Users

Description Security group to which all users will be assigned.


Defaults to MAXEVERYONE. Required at UI level.

Validation


When creating template data, MAXEVERYONE will be replaced with the provided value. Same as MAXGROUP.GROUPNAME



Database Field Nonpersistent (ALLUSERGROUP)

Field Name Group for Administrative Users

Description Security group to which administrative users will be assigned.


Defaults to MAXADMIN. Required at UI level.

Validation


When creating template data, MAXADMIN will be replaced with the provided value. Same as MAXGROUP.GROUPNAME

Database Field Nonpersistent (ADMINUSERGROUP)

These fields will be displayed at the bottom of the screen and conditional UI will be used to hide the fields after the initial save is completed.

MAXVAR Changes

VARNAME VARVALUE Comments

TENANTADMINGRP MAXADMIN System level, not nullable, specifies the group that will be copied to create the administrative group for new tenants in a multi-tenant environment.

LOGINTEMPLATE TENANTLOGIN System level, not nullable, specifies the communication template to be used to send login information to new tenants in a multi-tenant environment.

Story 5

None.

Story 6

TBD



2.5 Dynamic (Runtime) Models

Story 1

A landlord creates a new record for a tenant. New fields will be populated for the new ‘TENANTREG’ table that identify the tenant with a human readable ‘code’ – TENANTCODE – an ALN field that is defined by the landlord and which users of the tenant system need to enter at login. In future, we will look to automatically pass the tenant into the system. The TENANTCODE will be translated into a TENANTID that is used internally in the system. Because using an integer is more efficient for system processing and remembering an ALN field is more user friendly both values are required. Each must be unique. The same rules for protecting against hazardous characters that are used for loginids should be used for this field when input on the login screen. The TENANTCODE will have an associated description that can be entered to provide more complete information. For example, a TENANTCODE could be ‘IBMUS’ the TENANTID could be ‘0002’ and the DESCRIPTION could be ‘International Business Machines, US Offices’. Contact data will be collected for the tenant and stored to the TENANTREG table. The database user, tenant admin user id and tenant admin language will also be defined on the TENANTREG table. This data is all for the ‘landlord’ to use and stored in the ‘landlord’ context.

Not all user and person data will be entered here – a single administrative user will be configured that can then configure the rest of the tenant system. The application will need to create user and person data in the context of the tenant, not the ‘landlord’. A method of packaging up the required data into memory and switching context is required. The process will be as follows:

1. Before saving a new tenant, substitute a db admin user (process to define/obtain this user is TBD) for the entered TENANTDBUSERID. This allows the tenant temporary access to template data in order to clone it.

2. Switch context to the new tenant. 3. Insert the following data with SQL rather than through the Mbo framework:

a. The new user & person (see below for value mapping). b. Some template data. The user must be added to the MAXADMIN (or equivalent) group in order to

complete step 7 below (password assignment and email generation). The associated applicationauth, maxgroup, and groupuser template data must be inserted . The required commtemplate must be added as well.

4. Switch context to the landlord. 5. Update the new tenant record to the TENANTDBUSERID value entered in the UI and save. 6. Switch context to the new tenant. 7. Using the Mbo framework, update the new user's password & email flags (see below). Save to send email

using normal business logic. 8. Switch context to landlord.

The initial values entered for the new user in addition to the standard defaults:

Source Tenant destination Comments

TENANTREG.TENANTLOGINID MAXUSER.LOGINID

TENANTREG.TENANTLOGINID MAXUSER.USERID UPPER - tied to maxtype

TENANTREG.TENANTLOGINID MAXUSER.PERSONID UPPER - tied to maxtype

Default from template MAXUSERSTATUS domain?

MAXUSER.STATUS

Default from template USERTYPE domain? MAXUSER.TYPE

The initial values entered for the new person in addition to the standard defaults:



Source Tenant destination Comments

TENANTREG.TENANTLOGINID MAXUSER.PERSONID

TENANTREG.FIRSTNAME PERSON.FIRSTNAME

TENANTREG.LASTNAME PERSON.LASTNAME

FIRSTNAME + LASTNAME PERSON.DISPLAYNAME

Default from template PERSONSTATUS domain?

PERSON.STATUS

Default from template TRANSEMAILELECTION domain?

PERSON. TRANSEMAILELECTION

Should we be copying the phone and address? Check with partners.

The final step in saving a new tenant (see step 7 above) is to auto-generate a password and send it via email to the tenant contact email address.. Unlike the template data steps, this process does use the MBO framework to leverage existing functionality in the Users application. The following fields on the new user & person are populated and the user is saved.

Field Name <None>

Description


CRYPTOX

Validation


Randomly generated value using existing password generator

Database Field MAXUSER.PASSWORDINPUT

Field Name <None>

Description


CRYPTOX

Validation


Randomly generated value using existing password generator

Database Field MAXUSER.PASSWORDCHECK

Field Name <None>

Description


Validation




Set value to 1

Database Field MAXUSER.FORCEEXPIRATION

Field Name <None>

Description


Validation


Set value to 1

Database Field MAXUSER.EMAILPSWD

Field Name <None>

Description


Validation


Email address of the tenant admin; source is TENANTREG. PRIMARYEMAIL.

Database Field PERSON.PRIMARYEMAIL

These values are added in the context of the new tenant. When the user is saved the save business logic generates an e-mail with the password using the PWRESET communication template. This same process is used when the landlord resets the tenant admin password via an action. It is sent to the e-mail address specified in the TENANTREG.PRIMARYEMAIL attribute. A separate process for communicating the userid and tenantecode for the new tenant is specified in Story 3 below.

MAXGROUP and APPLICATIONAUTH will be ‘template tables’ so data will be copied for use by each tenant. This is how default users and authorizations will be created. The default users include MAXREG and MXINTADM plus the new Tenant administrative user similar to the ‘MAXADMIN” user and the default groups include MAXREG, MAXEVERYONE, MAXDEFLTREG, and MAXADMIN or whatever equivalent groups the ‘landlord’ administrator has created as defined in the associated system MAXVARS. The new tenant administrative user will be added to the same groups as the ‘MAXADMIN’ user in the system as identified by the mxe.adminuser property.

Story 2

A new ‘Change Status’ action is needed. It should be located near the top of the menu.

Changing the status of a tenant will disable login for all user ids for the tenant. No changes will be made to the user records themselves. When a tenant’s status is changed to inactive their users that are currently logged will be allowed to continue their work but when their session ends via logout or timeout they will not be able to log back in to the system.

A new ‘Reset Password’ action is needed. It should be located just below the ‘Change Status’ action.

A standard confirmation dialog confirming that the password should be changed should be presented before the process is initiated to ensure a password is not accidentally reset. When the action is performed, a new password



should be generated and e-mailed to the user just as it was when the tenant was initially created. The new password should also be set to expire on first login.

Story 3

An e-mail will be sent using the standard communication template methodology. The communication template is determined by a MAXVAR value as specified elsewhere in this spec to enable changes to be made to the template and prior versions to be kept. Story 4

Data in the system can be designated as ‘template data’. Template data are rows in tables designated with a tenantid of 0. When a new tenant is on-boarded, all data designated in this fashion will be copied for the new tenant and their records will be designated with their tenant id. For the admin user and group names that are collected on the tenantreg table will update the associated values on the new tenant rows in the new tables. Story 5

A new dialog is needed if a tenant enters an admin user login id that cannot be converted to a valid USERID and PERSONID automatically. This dialog will display a truncated string of the loginid shortened to fit into the field. It will give the user the option to use this value or specify something else. Story 6

Story 6 - As a tenant I need to be able to update information about my organization such as billing contacts and addresses for my contract with the landlord.

2.6 Finite State Machines (optional)

N/A

2.7 Other

None

3. System Structure Flows

3.1 Error Flows

Errors will need to be defined for the following situations:

The administrative user being created for a tenant already exists for that tenant.

The system can’t connect to the database with the tenant database user information.

The e-mail server is not accessible so the login information cannot be sent for creating a new user or resetting a password from Steve H – there is new email reprocessing in 7.5.0.3 – see if we can leverage that

When setting a password the personid for the userid cannot be located.

When setting a password the e-mail address for the personid for the userid cannot be located.



Missing other required fields on person or user as specified by the implementation.

In addition, tenants cannot be deleted, they can only be deactivated in this iteration. In future, delete rules for removing tenant records, reversing database configurations and purging tenant data will be addressed.

3.2 Cross-Component Flows

The login process will pass the Tenant Code that will correspond to the Tenant Code entered into the system.

Context switching will be used to create tenant-specific data from master/’landlord’ data.

3.3 Cross-Product Flows (not applicable to component design)

None

4. Other Design Considerations



4.1 Open Source

None.

5. APIs, External Interfaces and Semantics

5.1 Command Line Support

None

5.2 Programmatic Interfaces (APIs)

None

5.3 External Messages

None

5.4 User Assistance Provided

See documentation plan for details

6. Multi-Customer Implications

The entire scope of this enhancement is to better support multi-customer environments. The entire document

relates to this section.

7. Compatibility, Upgrade, and Coexistence

7.1 Compatibility

DB2 10.1 Maximo Version 7.5.next WebSphere 7, 8?



7.2 Upgrade

There is no upgrade in this iteration – it is for new installs only. Upgrade of all functionality will be covered in another iteration.

7.3 Coexistence

N/A

7.4 Interaction with other Tivoli Products/Components

N/A

8. Installation and Configuration

8.1 Upgrade

There is no upgrade in this iteration – it is for new installs only. Upgrade of all functionality will be covered in another iteration.

8.2 Installation and Packaging

N/A

8.3 Configuration

A tenant-specific database user id must be defined in the RDBMS prior to registering a new tenant in the application. Tables will be defined as ‘delta storage’ enabled (or not). Nothing ‘special’ will need to be done for delta storage configuration data. Non ‘delta storage’ configuration data will be duplicated for each tenant. The mail.smtp.host property must be populated with a valid value for much of the application functionality to work.

8.4 Post Install Configuration

None of the configuration for this enhancement is done via the installer.



8.5 Installability

N/A

9. Reliability, Availability and Serviceability (RAS) and Maintainability

9.1 Reliability and Availability

Performance and availability are key factors in the success of a multi-tenant SaaS implementation and are being considered in every enhancement. Specific areas considered for this enhancement are caching, data isolation, no system configuration impacting the operation of a tenant’s system without warning and no tenant operation impacting another tenant’s operation.

9.2 Serviceability

Standard messages and logging will be used for serviceability. Logging has been added for copying template data in addition.

9.3 Maintainability

N/A

10. Accessibility

N/A

11. Performance

Performance and availability are key factors in the success of a multi-tenant SaaS implementation and are being considered in every enhancement. Specific areas considered for this enhancement are caching, data isolation, no system configuration impacting the operation of a tenant’s system without warning and no tenant operation impacting another tenant’s operation. See the detailed performance plan document for more detail.

12. Security and Authentication



12.1 Encryption/Cryptography

None.

12.2 Authentication

Security considerations are being tracked separately for this project. See the security and technical specifications attached to their related Epics.

12.3 Authorization

‘Landlords’ may want the ability to authorize specific tenants to a subset of the applications installed on their system. The tenants can then further authorize their users. This capability is outside the scope of this epic but is planned for the project.

13. Usability

A key driver in a SaaS environment is the cost of operation. Usability is key so that tenants are not making costly contact with the ‘landlord’ for assistance in using the software. This will be especially important when providing self-service and end user applications. In addition, wherever possible automated processes should be enabled so the system can run without human intervention. Processes such as automated de-activation of tenants and associated users, approval of new tenants and creation of database configuration should be as seamless as possible.

14. Documentation

Tasks and topics that must be documented include:

• Configuring a template tenant admin security group

• Reviewing and modifying the PWRESET communication template

• Registering a new tenant

Existing topics that will be relevant to this task and may be incorporated include

• Setting up e-mail

• Password requirements/Automatic password generation

• Allowed special characters

15. Globalization

Standard processes for globalization will be followed.



16. Privacy

Standard privacy measures will be incorporated.

17. Educational Services

Nothing specific to this enhancement but Educational Services for multi-tenancy as a whole will need to be evaluated.

18. Intellectual Property

<removed>



19. Test and Testability

19.1 Development / Unit Test

1. Create a template tenant admin group.

2. Create a new tenant.

3. Retrieve password from e-mail.

4. Retrieve login information from e-mail

5. Log in as new tenant.

6. Validate permissions of tenant admin user.

7. Validate template and master data is created correctly.

8. Change status of tenant and validate status changes of associated users.

9. Change password of tenant admin, retrieve from e-mail and login.

10. Create a new tenant with a loginid longer than allowed in the userid/personid fields (30 characters by

default).

11. Include steps to test error flow failures

19.2 Testability Considerations

Need e-mail enabled on the test server.

19.3 External Tool Dependency

N/A

19.4 Internal Tool Dependency

Standard tools for JUnit and automated testing will be used.

20. Down Stream Component Design Documentation



None.