User Replication & Management

This function 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);
  

• Then initialize the Administration web service. Click here to learn how to do this. 

• 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

Complete Example

Below is a full example of the ADDUSER function. To use it for yourself, carry out the following the steps:

1. Copy the code and save it as ws_adduser.jsp.
2. Put the file in the root folder, which is Yellowfin/appserver/webapps/ROOT.
3. Adjust host, port, admin user and user to add details according to your environment.
4. Run http://<host>:<port>/ws_adduser.jsp from your Internet browser.

<%            
/*              ws_adduser.jsp                  */
%>


<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<%@ page import="com.hof.util.*, java.util.*, java.text.*" %> 
<%@ page import="com.hof.web.form.*" %>
<%@ page import="com.hof.mi.web.service.*" %>
<%
AdministrationServiceService s_adm = new AdministrationServiceServiceLocator("localhost",8080, "/services/AdministrationService", false);        // adjust host and port number

AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService();

AdministrationServiceRequest rsr = new AdministrationServiceRequest();


rsr.setLoginId("admin@yellowfin.com.au");          // provide your Yellowfin webservices admin account
rsr.setPassword("test");                           // change to be the password of the account above
rsr.setOrgId(1);
rsr.setFunction("ADDUSER");


AdministrationPerson ap = new AdministrationPerson();


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");
rsr.setPerson(ap);


AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

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

This function creates users in bulk. It works similar to the ADDUSER function, however this requires that you pass an array of AdministrationPerson objects. Note: Ensure that you mention the proper name of this function, which is ADDUSERS.

Complete Example

Below is a complete example of the ADDUSER function. This example code adds two new Yellowfin users, user1@yellowfin.com.au and user2@yellowfin.com.au, in the default organization.

To use it for yourself, carry out the following the steps:

1. Copy the code and save it as ws_addusers.jsp.
2. Put the file in the Yellowfin/appserver/webapps/ROOT folder.
3. Adjust the host, port, admin user and users to add details according to your environment.
4. Run http://<host>:<port>/ws_addusers.jsp from your Internet browser.

<%            
/*              ws_addusers.jsp                 */
%>


<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<%@ page import="com.hof.util.*, java.util.*, java.text.*" %> 
<%@ page import="com.hof.web.form.*" %>
<%@ page import="com.hof.mi.web.service.*" %>

<%
AdministrationServiceService s_adm = new AdministrationServiceServiceLocator("localhost",8080, "/services/AdministrationService", false);        // adjust host and port number

AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService();
AdministrationServiceRequest rsr = new AdministrationServiceRequest();

rsr.setLoginId("admin@yellowfin.com.au");          // provide your Yellowfin webservices admin account
rsr.setPassword("test");                           // change to be the password of the account above
rsr.setOrgId(1);
rsr.setFunction("ADDUSERS");

AdministrationPerson[] ap = new AdministrationPerson[2];

ap[0] = new AdministrationPerson();
ap[0].setUserId("user1@yellowfin.com.au");         
ap[0].setFirstName("user1");
ap[0].setLastName("Lastname1");
ap[0].setRoleCode("YFREPORTCONSUMER");          
ap[0].setPassword("test");                                 
ap[0].setEmailAddress("user1@yellowfin.com.au");

ap[1] = new AdministrationPerson();
ap[1].setUserId("user2@yellowfin.com.au");         
ap[1].setFirstName("user2");
ap[1].setLastName("Lastname2");
ap[1].setRoleCode("YFREPORTCONSUMER");          
ap[1].setPassword("test");                                 
ap[1].setEmailAddress("user2@yellowfin.com.au");


rsr.setPeople(ap);


AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

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

This function allows multiple users to be created, without adding duplicates. It works similar to the ADDUSERS function, however in this case, if the login ID or email of a potential new user is already in use, or the password isn't supplied, then a no exceptions error will be generated and the user will not be created. The response will contain an array of AdministrationPerson object with failed users that were not added.

• The code for this will be exactly like the ADDUSERS example. However, the function name would differ, as shown here:
  
  

  rsr.setFunction("ADDUSERSIGNOREDUPLICATES");

• Use this command to retrieve failed users:
  
  

  AdministrationPerson[] failed_users = rs.getPeople();

• The response will contain these parameters:
  
  

  Response Element	Data Type	Description
  StatusCode	String	Status of the web service call. Possible values include: SUCCESS FAILURE
  People	AdministrationPerson[]	Failed users whose accounts were not created.

The call will delete a specified user from Yellowfin. Note: To remove a user from a client organization, you should perform the REMOVEUSERACCESS call.

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("DELETUSER");

• The function requires AdministrationPerson object where you provide the user id (email address or Id depending on the Logon ID method) to delete:

  AdministrationPerson ap = new AdministrationPerson();
  
  ap.setUserId("test@yellowfin.com.au");                   // test@yellowfin.com.au should be existing Yellowfin user.
  rsr.setPerson(ap);
  

• After configuring the request, perform the call:

  AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
  

• Then initialize the Administration web service. Click here to learn how to do this. 

• The response will contain these parameters:
  
  

  Response Element	Data Type	Description
  StatusCode	String	Status of the web service call. Possible values include: SUCCESS FAILURE

Complete Example

Below is a complete example of the DELETEUSER function. To use it for yourself, carry out the following the steps:

1. Copy the below code and save it as ws_deleteuser.jsp.
2. Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
3. Adjust the host, port, admin user and user to delete details according to your environment.
4. Run http://<host>:<port>/ws_deleteuser.jsp from your Internet browser.

<%            
/*              ws_deleteuser.jsp              */
%>

<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<%@ page import="com.hof.util.*, java.util.*, java.text.*" %> 
<%@ page import="com.hof.web.form.*" %>
<%@ page import="com.hof.mi.web.service.*" %>

<%
AdministrationServiceService s_adm = new AdministrationServiceServiceLocator("localhost",8080, "/services/AdministrationService", false);        // adjust host and port number

AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService();

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

rsr.setLoginId("admin@yellowfin.com.au");          // provide your Yellowfin webservices admin account
rsr.setPassword("test");                           // change to be the password of the account above
rsr.setOrgId(1);
rsr.setFunction("DELETEUSER");


AdministrationPerson ap = new AdministrationPerson();

ap.setUserId("test@yellowfin.com.au"); 
rsr.setPerson(ap);

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);


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

This function retrieves an existing Yellowfin user's details. It accepts AdministrationPerson as a parameter where you can provide a user ID (email address or any other ID, depending on the Login ID method) to identify the user. For security reasons, passwords will not be returned and will be NULL.

The response will contain the AdministrationPerson object with full user details.

• Following is an example of this request:
  
  

  AdministrationServiceRequest rsr = new AdministrationServiceRequest();
  
  rsr.setLoginId("admin@yellowfin.com.au");
  rsr.setPassword("test");
  rsr.setOrgId(1);
  
  rsr.setFunction("GETUSER");

• Now provide the user ID via the AdministrationPerson object:
  
  

  AdministrationPerson ap = new AdministrationPerson();
  ap.setUserId("john.smith@yellowfin.com.au");
  rsr.setPerson(ap);

• Once the request is configured, perform the call:
  
  

  AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

• Initialize the Administration web service. Click here to learn how to do this. 

• The response will contain the following parameters:
  
  

  Response Element	Data Type	Description
  StatusCode	String	Status of the web service call. Possible values include: SUCCESS FAILURE
  Person	AdministrationPerson	Object with the user details

   

   

• To display the retrieved user details, use the following example:
  
  

  if ("SUCCESS".equals(rs.getStatusCode()) ) {
  	ap = rs.getPerson();
  	out.write("UserId:" + ap.getUserId() + "<br>");
  	out.write("Password:" + ap.getPassword() + "<br>");
  	out.write("FirstName:" + ap.getFirstName() + "<br>");
  	out.write("LastName:" + ap.getLastName() + "<br>");
  	out.write("Initial:" + ap.getInitial() + "<br>");
  	out.write("SalutationCode:" + ap.getSalutationCode() + "<br>");
  	out.write("RoleCode:" + ap.getRoleCode() + "<br>");
  	out.write("EmailAddress:" + ap.getEmailAddress() + "<br>");
  	out.write("LanguageCode:" + ap.getLanguageCode() + "<br>");
  	out.write("IpId:" + ap.getIpId() + "<br>");
  	out.write("TimeZoneCode:" + ap.getTimeZoneCode() + "<br>");
  	out.write("Status:" + ap.getStatus() + "<br>");
  } else {
  	out.write("Failure");
  	out.write(" Code: " + rs.getErrorCode());
  }
  
  
  

Complete Example

Below is a complete example of the GETUSER function. To use it for yourself, carry out the following the steps:

1. Copy the code and save it as ws_getuser.jsp.
2. Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
3. Adjust the host, port, admin user and user to get details according to your environment.
4. Run http://<host>:<port>/ws_getuser.jsp from your Internet browser.

<%            
/*              ws_getuser.jsp              */
%>

<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<%@ page import="com.hof.util.*, java.util.*, java.text.*" %> 
<%@ page import="com.hof.web.form.*" %>
<%@ page import="com.hof.mi.web.service.*" %>
<%
AdministrationServiceService s_adm = new AdministrationServiceServiceLocator("localhost",8080, "/services/AdministrationService", false);        // adjust host and port number

AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService();
AdministrationServiceRequest rsr = new AdministrationServiceRequest();

rsr.setLoginId("admin@yellowfin.com.au");          // provide your Yellowfin webservices admin account
rsr.setPassword("test");                           // change to be the password of the account above
rsr.setOrgId(1);
rsr.setFunction("GETUSER");

AdministrationPerson ap = new AdministrationPerson();
ap.setUserId("john.smith@yellowfin.com.au");
rsr.setPerson(ap);

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

if ("SUCCESS".equals(rs.getStatusCode()) ) {
	ap = rs.getPerson();
	out.write("User Id:" + ap.getUserId() + "<br>");
	out.write("Password:" + ap.getPassword() + "<br>");
	out.write("First Name:" + ap.getFirstName() + "<br>");
	out.write("Last Name:" + ap.getLastName() + "<br>");
	out.write("Initial:" + ap.getInitial() + "<br>");
	out.write("Salutation Code:" + ap.getSalutationCode() + "<br>");
	out.write("Role Code:" + ap.getRoleCode() + "<br>");
	out.write("Email Address:" + ap.getEmailAddress() + "<br>");
	out.write("Language Code:" + ap.getLanguageCode() + "<br>");
	out.write("IpId:" + ap.getIpId() + "<br>");
	out.write("Time Zone Code:" + ap.getTimeZoneCode() + "<br>");
	out.write("Status:" + ap.getStatus() + "<br>");
} else {
	out.write("Failure");
	out.write(" Code: " + rs.getErrorCode() );
}
%>

This functions retrieves details of all the users in a specified client organization. The information is retrieved in an array of AdministrationPerson objects. If a client organization is not specified, then all the users will be retrieved. You can use the setParameters() method to specify a searching criteria for users being retrieved. For security reasons, passwords will not be returned and will be NULL.

• Here's an example of a request to retrieve users:
  
  

  AdministrationServiceRequest rsr = new AdministrationServiceRequest();
  
  rsr.setLoginId("admin@yellowfin.com.au");
  rsr.setPassword("test");
  rsr.setOrgId(1);
  
  rsr.setFunction("GETALLUSERS");
  

• Specify a client organization, otherwise all the client organizations will get searched:
  
  

  rsr.setOrgRef("org1");
  
  String[] searchingCriteria = new String[] {"John","yellowfin.com.au"};
  rsr.setParameters(searchingCriteria);
  

  
  Searching Criteria: The GETALLUSERS function accepts an array of 2 Strings. The first string (searchingCriteria[0]) will be compared with Yellowfin database users’ first names, last names, email left or email right, using the condition LIKE ‘%John%’. The second string (searchingCriteria[1]) will be compared with email right (domain) of the Yellowfin database users.

• Once the request is configured, perform the call:
  
  

  AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

• Initialize the Administration web service. Click here to learn how to do this. 

• The response will contain the following parameters:
  
  

  Response Element	Data Type	Description
  StatusCode	String	Status of the web service call. Possible values include: SUCCESS FAILURE
  People	AdministrationPerson[]	Array of objects with the users’ details.

Complete Example

Below is a complete example of the GETALLUSERS function. To use it for yourself, carry out the following the steps:

1. Copy the code and save it as ws_getallusers.jsp.
2. Put the file in the Yellowfin/appserver/webapps/ROOT folder.
3. Adjust host, port, admin user and searching criteria according to your environment.
4. Run http://<host>:<port>/ws_getallusers.jsp from your Internet browser.

<%            
/*              ws_getallusers.jsp               */
%>


<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<%@ page import="com.hof.util.*, java.util.*, java.text.*" %> 
<%@ page import="com.hof.web.form.*" %>
<%@ page import="com.hof.mi.web.service.*" %>
<%
AdministrationServiceService s_adm = new AdministrationServiceServiceLocator("localhost",8080, "/services/AdministrationService", false);        // adjust host and port number

AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService();
AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("GETALLUSERS");

rsr.setOrgRef("org1");

String[] searchingCriteria = new String[] {"John","yellowfin.com.au"};
rsr.setParameters(searchingCriteria);

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

if ("SUCCESS".equals(rs.getStatusCode()) ) {
	out.write("Success. " + rs.getPeople().length + " people found.");
} else {
	out.write("Failure");
	out.write(" Code: " + rs.getErrorCode() );
}
%>

This function validates a Yellowfin user. It accepts AdministrationPerson as a parameter where you can provide user ID (email address or Id depending on the Login ID method) and password to identify the user.

The response will be SUCCESS if the user with provided details exists. The response will return code 25 (COULD_NOT_AUTHENTICATE_USER) if the user is not valid.

Here's an example of a basic request to call this function:

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("VALIDATEUSER");

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.

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

The response returned will contain these parameters:

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.

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

The response returned will contain these parameters:

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.

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

The response returned will contain these parameters: