1 /*
  2  * Copyright © [2008-2009] Novell, Inc.  All Rights Reserved.
  3  * 
  4  * USE AND REDISTRIBUTION OF THIS WORK IS SUBJECT TO THE DEVELOPER LICENSE AGREEMENT
  5  * OR OTHER AGREEMENT THROUGH WHICH NOVELL, INC. MAKES THE WORK AVAILABLE.  THIS WORK 
  6  * MAY NOT BE ADAPTED WITHOUT NOVELL'S PRIOR WRITTEN CONSENT.
  7  * 
  8  * NOVELL PROVIDES THE WORK "AS IS," WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, 
  9  * INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR 
 10  * A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  NOVELL, THE AUTHORS OF THE WORK, AND THE 
 11  * OWNERS OF COPYRIGHT IN THE WORK ARE NOT LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER 
 12  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, 
 13  * OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS IN THE WORK.
 14  */
 15 
 16 /**
 17 * @fileoverview 
 18 * This file defines the Identity class, which represents the identity of a user (usually)
 19 * within an enterprise.
 20 * @name Identity Class
 21 */
 22  
 23 /**
 24  * Constructs an instance of the Identity class based on passed-in properties.
 25  * @class
 26  * The Identity class is used to manage resource identities, primarily users, within Sentinel.
 27  * Each user of an enterprise's IT systems should have a set of meta-information available to help
 28  * identify that user from a security perspective, pursuant to local privacy laws. The Identity 
 29  * object is used to store that information and make some of it available in events, and the rest
 30  * available through interactive lookups.
 31  * <p>The class accepts a pre-defined set of Identity attributes, all of which (except for GUID,
 32  * which is auto-generated) are optional:
 33  * <ul>
 34  * <li>DistinguishedName: The full expression of the source directory's identity object
 35  * <li>FullName: The full name of the user
 36  *	<li>FirstName: The given name of the user
 37  *	<li>LastName: The user's surname
 38  *	<li>JobTitle: The user's job title
 39  *	<li>WorkForceId: The user's workforce identifier
 40  *	<li>OfficeCode: The internal postal code used to locate the user
 41  *	<li>PrimaryPhone: The user's primary phone contact information
 42  *	<li>PrimaryEmail: The user's primary e-mail address
 43  * </ul>
 44  * In addition to the above, you may also attach extended attribute information to the identity;
 45  * this information is stored separately in an ExtendedAttribute area that is not available to the
 46  * GUI lookup methods, but can be used for reporting.
 47  * <p>Further, user accounts which belong to this identity can be attached; see the {@link Account}
 48  * class for further information.
 49  * @constructor
 50  * @param {Hash} properties Initial properties (JSON notation) to define identity
 51  * @see Account
 52  */
 53 function Identity(properties) {
 54  	this.identityImpl =  new IdentityImpl(properties);
 55  	return this.identityImpl; 
 56 }
 57 
 58 /**
 59 * The save methods saves the identity object synchronously.
 60 * <p>Example:
 61 * <pre>
 62 * var myIden = new Identity({
 63 *			DistinguishedName:"cn=JoeSmith,ou=Active,ou=Users,o=Vault",
 64 *			FullName : "Joe Smith",
 65 *			FirstName : "Joe",
 66 *			LastName : "Smith",
 67 *			JobTitle : "QA",
 68 *			WorkForceId : "95502",
 69 *			OfficeCode : "VVA-100",
 70 *			PrimaryPhone : "703-555-1212",
 71 *			PrimaryEmail : "joesmith@novell.com"});
 72 * myIden.save();
 73 * </pre>
 74 * @return {GUID}	GUID associated with the identity
 75 * @throws {String} Throws an string exception describing the error.
 76 */
 77 Identity.prototype.save = function() {
 78 	return this.identityImpl.save();
 79 };
 80 
 81 /**
 82 * Save an array of objects in the background, notifying via the callback of any issues.
 83 * <p>Example:
 84 * <pre>
 85 * var id1 = new Identity({
 86 *			DistinguishedName:"cn=JoeSmith,ou=Active,ou=Users,o=Vault",
 87 *			FullName : "Joe Smith",
 88 *			FirstName : "Joe",
 89 *			LastName : "Smith",
 90 *			JobTitle : "QA",
 91 *			WorkForceId : "95502",
 92 *			OfficeCode : "VVA-100",
 93 *			PrimaryPhone : "703-555-1212",
 94 *			PrimaryEmail : "joesmith@novell.com"});
 95 * var id2 = new Identity({
 96 *			DistinguishedName:"cn=JohnSmith,ou=Active,ou=Users,o=Vault",
 97 *			FullName : "John Smith",
 98 *			FirstName : "John",
 99 *			LastName : "Smith",
100 *			JobTitle : "Engineer",
101 *			WorkForceId : "95504",
102 *			OfficeCode : "VVA-100",
103 *			PrimaryPhone : "703-555-1213",
104 *			PrimaryEmail : "johnsmith@novell.com"});
105 * 
106 * var callback = function(idenarr,errmessage) {
107 * 	// do something with the original idenarr called with the saveBatch and the errmessage
108 *   // log(idenarr, errmessage)
109 * }
110 * var guids = Identity.saveBatch([id1,id2],callback);
111 * </pre> 
112 * @param {Identity[]} identarr  Array of Identity objects to save (length of array must be <= 100)
113 * @param {Callback}   callback Calls this function when an error occur saving the identities asynchronously
114 */
115 Identity.saveBatch = function(identarr, callback){
116 	return IdentityImpl.saveBatch(identarr, callback);
117 };
118 
119 /**
120 * Finds the identity.
121 * <p>Example:
122 * <pre>
123 * var myIdens = Identity.find({DistinguishedName: "cn=JoeSmith,ou=Active,ou=Users,o=Vault"});
124 * var myIdens = Identity.find({FullName : "Joe Smith",FirstName : "Joe"});
125 * </pre>
126 * @param {JSON} params JSON notation of the identity attributes to be matched
127 * @return {Identity[]}	Returns an array of Identities found; the array could be of size 0 if no identities are found for the search criteria.
128 * @throws {String} Throws an string exception describing the error.
129 */
130 Identity.find = function(params){
131 	return IdentityImpl.find(params);
132 };
133 
134 /**
135 * Attaches accounts to the Identity.
136 * <p>Example:
137 * <pre>
138 * var myIden = new Identity({
139 *			DistinguishedName:"cn=JoeSmith,ou=Active,ou=Users,o=Vault",
140 *			FullName : "Joe Smith",
141 *			FirstName : "Joe",
142 *			LastName : "Smith",
143 *			JobTitle : "QA",
144 *			WorkForceId : "95502",
145 *			OfficeCode : "VVA-100",
146 *			PrimaryPhone : "703-555-1212",
147 *			PrimaryEmail : "joesmith@novell.com"});
148 * 
149 * Account acc1 = new Account({Name:"JoeSmith",
150 *			Authority:"cn=JoeSmith,ou=Active,ou=Users,o=Vault",
151 *			Status: "A",
152 *			CustomerId : 5})
153 * Account acc2 = new Account({Name:"JohnSmith",
154 *			Authority:"cn=JohnSmith,ou=Active,ou=Users,o=Vault",
155 *			Status: "A"})
156 * 
157 * myIden.attachAccounts(new Array(acc1,acc2));
158 * myIden.save();
159 * </pre>
160 * @param {Account[]} accounts  Array of Account objects
161 */
162 Identity.prototype.attachAccounts = function(accounts) {
163 	this.identityImpl.attachAccounts(accounts);
164 };