The central question confronting individuals during the creation of a new app is : How to model a user of my app? This article shows the best practices in ApiOmat, and gives some examples about the usage of the User class.

images/download/attachments/34177181/userOverview.png

In ApiOmat, existing data models or classes are encapsulated in modules. One module is automatically contained in every app: the Basics module. If you are searching for a representation of a user, you will find it right in this module: the User class. A user represents one installation of your app and therefore has to be unique per device. You will find examples below Creation and loading of a new user. This unique relation is necessary to ensure a proper authentication of requests against ApiOmat. If the same user would be used on more than one device, no clear separation of data would be possible. If no user would be used at all, only free accessible data could be retrieved. Additionally,other modules like Push or Facebook are based on the concept of unique users per device and would not work when sharing users.

User Insights

A user contains some basic attributes, which are primarily used for authentication:

userName – Unique user name or email address (obligatory)
password – Password of the user (obligatory)
firstName – First name of the user
lastName – Last name of the user
dateOfBirth – User’s date of birth

It can be seen that every user has to have at least a userName and password.

A deeper look into the class shows an attribute named dynamicAttributes; this map is not writable and only for internal use. It is used to store additional user attributes in a dynamic way, which are injected by other modules. For example, if you add the Push module to your app, your user will automatically be enriched with some more attributes seen in the SDK to store the Push tokens.

Creation and loading of a new user

If you select the user class in the left menu and switch to the SDK tab afterwards, you will see example code for user creation in all SDK languages (Javascript, iOS,…). The following code will automatically create a new user if it did not exist before:

Android

// Create a new member/user of your app
User myUser=new User();
myUser.setUserName("johnDoe");
myUser.setPassword("1,618");
 
// configure datastore with user credentials
Datastore.configureWithCredentials( myUser );
// Try to load user or create new one if not exists
myUser.loadMeAsync(new AOMEmptyCallback() {
	@Override
	public void isDone(ApiomatRequestException exception) {
		if(exception!=null) {
			myUser.saveAsync(null);
		}
	}
} );

Objective-C

// Create a new user of your app
AOMUser *myUser = [[AOMUser alloc] init];
[myUser setUserName:@"johnDoe"];
[myUser setPassword:@"1,618"];
 
// configure datastore with user credentials
[AOMDatastore configureWithUser:myUser];
 
// Try to load user or create new one if not exists
[myUser loadAsyncWithBlock:^(NSError *error) {
   if(error)
   {
      [myUser saveAsyncWithBlock:NULL];
   }
}];

JavaScript

// Create a new member/user of your app
var myUser = new Apiomat.User();    
myUser.setUserName("johnDoe");
myUser.setPassword("1,618");
 
// configure datastore with user credentials
Apiomat.Datastore.configureWithCredentials(myUser);
 
var saveCB = {
    onOk : function() {
        console.log("saved");
        //Now you can create objects of your class with this new user..
    },
    onError : function(error) {
        console.log("Some error occured: (" + error.statusCode + ")" + error.message);
    }
};
 
// Try to load user or create new one if not exists
myUser.loadMe({
    onOk : function() {
        //Now you can do sth with loaded object
    },
    onError : function(error) {
        // and save it
		myUser.save(saveCB);
    }
});

Swift

// Create a new user of your app
let user = User(userName: "johnDoe", password: "1,618")
// configure datastore with user credentials
DataStore.configureWithCredentials(user: user)
 
// Try to load user or create new one if not exists
user.loadMe { (error) in
	if(error) {
		user.save(completion: { (error) in
		})
   }
}

The workflow in creating a user is always the same:

Create a user
Call Datastore.configure(), which will set the user’s credentials for the following requests to ApiOmat
Load an existing user (loadMe())
Or: save the user(save())

It is very important to call Datastore.configure() before the first request. Otherwise the communication layer will not have the necessary information to communicate with ApiOmat.

Reset password

While all other attributes of a user can be set using the setter methods, special methods are used to reset password:

resetPassword() – Sends a generated password to the user via email. This is useful if he forgot the old password. It is necessary to use a valid email address as userName to make this method work!
changePassword – Changes the password to a new value. The Datastore gets automatically reconfigured with the new credentials afterwards.

Extending user class

images/download/attachments/34177181/apiOmat_UserManagement_userClasses.PNG
In some cases, the existing attributes in the user class will not suffice the needs of you app. Then, you can simply build you own class in Class Editor (e.g. JiraUser in the image), and inherit from the user class. Your own class will inherit all attributes and behaviour from the standard user class and can be used for authentication, too. The example code in SDK tab will show you how:

Android

// Create a new member/user of your app
JiraUser myUser=new JiraUser();
myUser.setUserName("johnDoe");
myUser.setPassword("1,618");
 
// configure datastore with user credentials
Datastore.configureWithCredentials( myUser );
...

Objective-C

// Create a new user of your app
JiraUser *myUser = [[JiraUser alloc] init];
[myUser setUserName:@"johnDoe"];
[myUser setPassword:@"1,618"];
 
// configure datastore with user credentials
[AOMDatastore configureWithUser:myUser];

JavaScript

//Create a new member/user of your app
var myUser=new Apiomat.JiraUser();
myUser.setUserName("johnDoe");
myUser.setPassword("1,618");
 
//configure datastore wit user credentials
Apiomat.Datastore.configureWithCredentials(myUser);
/* ... */

Swift

// Create a new user of your app
let user = JiraUser(userName: "johnDoe", password: "1,618")
// configure datastore with user credentials
DataStore.configureWithCredentials(user: user)

Roles and security

An authentication with a user permits access to all data with the User and Guest rights. An extension to this rights management is also possible: You can find additional documentation for security for complex cases here.

The default access rules of the basics.User class allow all users to read the data of other users. You can either create a subclass and modify the access rules, or change the configuration of the module "Basics" accordingly (see Basics Module).

Billing

Based on the usage of the User class the number of active users is calculated, which is one part used for billing purposes. An active user is a user who made requests against ApiOmat or received push messages in the last 30 days. To ensure a proper calculation, the implementation of the user in your app must follow the above advices (one app installation = one unique user). Misuse or sharing of users is detected.

User Management

User Insights

Creation and loading of a new user

Reset password

Extending user class

Roles and security

Billing

Search results