User Replication & Management

User replication involves synchronising each user in the OEM application with a named user in Yellowfin.

This allows Yellowfin to identify the user who is logged in, and to apply any restrictions that may be required. Synchronisation is usually performed using web service calls from the OEM application to Yellowfin. This can also be managed manually if users in the OEM application are generally static.

This section will outline how to create, manipulate, and delete users via web services. It is assumed that the web service is called to mirror user changes immediately after a user modification is made in the OEM application.

Main Functions

Creates a new user account in Yellowfin.

Here's a basic request to create a new Yellowfin user:

AdministrationServiceRequest rsr = new AdministrationServiceRequest();


rsr.setLoginId("admin@yellowfin.com.au");
rsr.setPassword("test");
rsr.setOrgId(1);

rsr.setFunction("ADDUSER");

If you need to create a new user in a specific client organization, add this to your code
```
rsr.setOrgRef("org1");      // A new user will be added to the client with "org1" as an organization reference ID
```
If you do not define the orgRef parameter, the new user will be created in the default (primary) organization.

The ADDUSER function requires AdministrationPerson object where you define the new Yellowfin user details:
```
AdministrationPerson ap = new AdministrationPerson();
```

To create a new user, you need to fill these mandatory parameters: UserId, FirstName, LastName, RoleCode, Password, EmailAddress:

ap.setUserId("john.smith@yellowfin.com.au");  // if Yellowfin authentication option is set "email address"
ap.setFirstName("John");
ap.setLastName("Smith");
ap.setRoleCode("YFREPORTCONSUMER");                // Yellowfin role codes can be found performing this query against 
												   // Yellowfin configuration database: SELECT * FROM OrgRole

ap.setPassword("test");                    		   // Password must comply with your Yellowfin password policy
ap.setEmailAddress("john.smith@yellowfin.com.au");

Other parameters of AdministrationPerson object are optional.

Pass the 'ap' object to the request:
```
rsr.setPerson(ap);
```

Once the request is configured, carry out the call:

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

The following code will call the Yellowfin web service to delete a user:

AdministrationServiceRequest rsr = new AdminstrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();

person.setUserId("test@yellowfin.com.au");

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(new Integer(1));
rsr.setFunction("DELUSER");
rsr.setPerson(person);

rs = AdministrationService.remoteAdministrationCall(rsr);

if ("SUCCESS".equals(rs.getStatusCode()) ) {
				
out.write("Success");
				
} else {
			
out.write("Failure");
out.write(" Code: " + rs.getErrorCode());
				
}

This code will return SUCCESS in rs.getStatusCode(), otherwise it will return an error message explaining why the user deletion process failed.

This function will delete a user from Yellowfin. The details in the AdministrationPerson object will be used in the user deletion process.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices eg. admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “DELUSER” or “DELETEUSER”		Web services function
Person	AdministrationPerson	The AdministrationPerson object holding all of the user’s details for the user creation process

These are the parameters that you need to set in the AdministrationPerson object:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the Yellowfin user. This can be the user ID or the email address, depending on the Logon ID method

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Retrieving & Validating User Information

Once a user has been created, the user's details can be retrieved using a web service call. The User ID field in the AdministrationPerson object is used to identify the user. As a result, a populated AdministrationPerson object will be returned. For security reasons, passwords will not be returned and will be NULL. User information can also be validated against the application in this section.

The following code will call the Yellowfin web service to retrieve a user’s details:

AdministrationServiceRequest rsr = new AdminstrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();

Person.setUserId("testuser@yellowfin.com.au");

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(new Integer(1));
rsr.setFunction("GETUSER");
rsr.setPerson(person);

rs = AdministrationService.remoteAdministrationCall(rsr);

if ("SUCCESS".equals(rs.getStatusCode()) ) {
				
out.write("Success");
				
} else {
			
out.write("Failure");
out.write(" Code: " + rs.getErrorCode());
				
}

This code will return an AdministrationPerson object with the user’s details and SUCCESS in the rs.getStatusCode(), otherwise it will return an error message explaining why the process failed.

This function will retrieve the details of a particular user in Yellowfin. The details in the AdministrationPerson object will be used in the retrieval process.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices eg. admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “GETUSER”		Web services function
Person	AdministrationPerson	The AdministrationPerson object holding the Yellowfin user’s User ID for the retrieval process

These are the parameters that you need to set in the AdministrationPerson object:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the Yellowfin user. This can be the user ID or the email address, depending on the Logon ID method

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Person

AdministrationPerson

The AdministrationPerson object holding all of the returned user’s details

The following code will call the Yellowfin web service to retrieve a user’s details via their internal IpId:

AdministrationServiceRequest rsr = new AdminstrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();

Person.setIpId(5);

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(new Integer(1));
rsr.setFunction("GETUSERBYIP");
rsr.setPerson(person);

rs = AdministrationService.remoteAdministrationCall(rsr);

if ("SUCCESS".equals(rs.getStatusCode()) ) {
				
out.write("Success");
				
} else {
			
out.write("Failure");
out.write(" Code: " + rs.getErrorCode());
				
}

This code will return an AdministrationPerson object with the user’s details and SUCCESS in the rs.getStatusCode(), otherwise it will return an error message explaining why the process failed.

This function will retrieve the details of a particular user in Yellowfin by looking up their IP ID. The details in the AdministrationPerson object will be used in the retrieval process.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices eg. admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “GETUSERBYIP”		Web services function
Person	AdministrationPerson	The AdministrationPerson object holding the Yellowfin user’s User ID for the retrieval process

These are the parameters that you need to set in the AdministrationPerson object:

AdministrationPerson Element	Data Type	Description

IpId|Integer|IP ID of the Yellowfin User|

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Person

AdministrationPerson

The AdministrationPerson object holding all of the returned user’s details

This function will retrieve users from Yellowfin based on a specific search string. This string is compared against the user’s first name, last name, and email address.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices i.e admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “GETUSERSFROMSEARCH”		Web services function
Parameters	Array (String)	Search string to match against Yellowfin users’ first names, last names, and email address

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

People

Array (AdministrationPerson)

An array of AdministrationPerson objects. These objects hold the returned users’ details that match the search string

The following code will call the Yellowfin web service to validate a user:

AdministrationServiceRequest rsr = new AdminstrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();

person.setUserId("admin@yellowfin.com.au");

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setFunction("VALIDATEUSER");
rsr.setPerson(person);

rs = AdministrationService.remoteAdministrationCall(rsr);

This code will return an AdministrationPerson object of the particular user if successful; otherwise it will return an error message explaining why the user validation process failed.

This function will validate a specified Yellowfin user, checking if the user currently exists within the application. The details in the AdministrationPerson object will be used in the user validation process.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices eg. admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “VALIDATEUSER”		Web services function
Person	AdministrationPerson	The AdministrationPerson object holding the Yellowfin user’s User ID for the retrieval process

These are the parameters that you need to set in the AdministrationPerson object:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the Yellowfin user. This can be the user ID or the email address, depending on the Logon ID method

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Person

AdministrationPerson

The AdministrationPerson object holding all of the returned user’s details

The following code will call the Yellowfin web service to validate a user’s password:

AdministrationServiceRequest rsr = new AdminstrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();

person.setUserId("testuser@yellowfin.com.au");
person.setPassword("test");

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(new Integer(1));
rsr.setFunction("VALIDATEPASSWORD");
rsr.setPerson(person);

rs = AdministrationService.remoteAdministrationCall(rsr);

This code will check if the password is expired and will return FAILURE in the rs.getStatusCode() if it is not, otherwise it will return SUCCESS.

This function will validate a Yellowfin user’s password. The details in the AdministrationPerson object will be used in the password validation process.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices eg. admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “VALIDATEUSER”		Web services function
Person	AdministrationPerson	The AdministrationPerson object holding the Yellowfin user’s User ID for the retrieval process

These are the parameters that you need to set in the AdministrationPerson object:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the Yellowfin user. This can be the user ID or the email address, depending on the Logon ID method
Password	String	Password of the Yellowfin user

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Manipulating User Information

A user's details can be modified at a later time using a web service call. The User ID field in the AdministrationPerson object is used to identify the user, so this cannot be changed. The rest of the fields within an AdministrationPerson object are populated with the new changes. For security reasons, the user's password cannot be changed with this web service call, but with a separate CHANGEPASSWORD function (below).

The following code will call the Yellowfin web service to edit a user’s details:

AdministrationServiceRequest rsr = new AdminstrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();

person.setUserId("testuser");
person.setFirstName("John");
person.setLastName("Doe");
person.setInitial("F");
person.setSalutationCode("MR");
person.setRoleCode("YFADMIN");
person.setEmailAddress("testuser@yellowfin.com.au")

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(new Integer(1));
rsr.setFunction("UPDATEUSER");
rsr.setPerson(person);

rs = AdministrationService.remoteAdministrationCall(rsr);

This code will return an AdministrationPerson object with the user’s details and SUCCESS in the rs.getStatusCode(), otherwise it will return an error message explaining why the process failed.

This function will update a specified Yellowfin user’s details. The details in the AdministrationPerson object will be used in the update process.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices eg. admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “UPDATEUSER”		Web services function
Person	AdministrationPerson	The AdministrationPerson object holding the Yellowfin user’s User ID for the retrieval process

These are the parameters that you can set in the AdministrationPerson object:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the Yellowfin user. This can be the user ID or the email address, depending on the Logon ID method
Password	String	Password of the Yellowfin user
FirstName	String	First name of of the Yellowfin user
LastName	String	Last name of of the Yellowfin user
Initial	String	Middle name of the Yellowfin user
SalutationCode	String	Title of the Yellowfin user. Possible values include: DR MISS MR MRS MS
RoleCode	String	Yellowfin role. The specified role here can be the Org Reference Code (YFADMIN) or the name of the role (Yellowfin Administrator)
EmailAddress	String	Email address of the Yellowfin user
LanguageCode	String	Two letter code for the preferred language
IpId	Integer	Internal Yellowfin IP ID
TimeZoneCode	String	The TimeZoneCode of the Yellowfin user. See appendix for valid values.
Status	String	Indicates a user status. Can be one of the following: ACTIVE INACTIVE INACTIVEWITHEMAIL

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Person

AdministrationPerson

The AdministrationPerson object holding all of the updated user’s details

The following code will call the Yellowfin web service and change the password for the specified Yellowfin user:

AdministrationServiceRequest rsr = new AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();

person.setUserId("test@yellowfin.com.au");
person.setPassword("testtest");

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(new Integer(1));
rsr.setFunction("CHANGEPASSWORD");
rsr.setPerson(person);

rs = AdministrationService.remoteAdministrationCall(rsr);

The code will return SUCCESS in rs.getStatusCode(), otherwise it will return an error explaining why the process failed.

This function will change a specified Yellowfin user’s password.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices eg. admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “CHANGEPASSWORD”		Web services function
Person	AdministrationPerson	The AdministrationPerson object holding the Yellowfin user’s User ID for the retrieval process

These are the parameters that you need to set in the AdministrationPerson object:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the Yellowfin user. This can be the user ID or the email address, depending on the Logon ID method
Password	String	New password of the Yellowfin user

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Content

Space Tools

Main Functions

Retrieving & Validating User Information

Manipulating User Information