Page History

Versions Compared

Old Version 20

changes.mady.by.user user-3484a

Saved on 28 Jan, 2018

compared with

New Version Current

changes.mady.by.user Wendy R

Saved on 14 Dec, 2020

Key

This line was added.
This line was removed.
Formatting was changed.

Comment: Updated for 8.0.98

Anchor

	top
	top

User replication involves synchronising each user in the OEM third-party 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 Synchronization is usually performed using web service calls from the OEM the third-party application to Yellowfin. This can also be managed manually if users in the OEM the third-party 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 third-party application.

Main User Management Functions

Anchor

	adduser
	adduser

ap.setUserId("john.smith@yellowfin.com.au"); // if Yellowfin authentication option is set "email address" ap.setFirstName("John"); ap.setLastName("Smith"); ap.setRoleCode("YFREPORTCONSUMER");

Expand

title	ADDUSER

This function creates a new user account in Yellowfin.

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

Code Block

language	java

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

Code Block

language	java

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,

Request Parameters

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "ADDUSER".
Person	AdministrationPerson	Object containing all of the new user’s details for the user creation process. See table below.
OrgRef	String	Client Org Internal Reference Id (optional). This will create a new user in the referenced Client Org. If this is not set, then the new user will be created in

the

default (primary)

organization

org.

Anchor

The ADDUSER function requires AdministrationPerson object where you define the new Yellowfin user details:

Code Block

language	java

AdministrationPerson ap = new AdministrationPerson();

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

	createuserap
	createuserap

These are the mandatory parameters that you need to set in the AdministrationPerson object to create a new user:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the new user. This can be the user ID or the email address, depending on the Logon ID method.
Password	String	Password of the new user. This must comply with Yellowfin's Password Policy.
FirstName	String	The first name of the new user.
LastName	String	The last name of the new user.
RoleCode	String	Set the user role for this new user. For example, YFREPORTCONSUMER. Note: You can get a list of Yellowfin's role codes from the configured database, for example, by using a SQL query: SELECT * FROM OrgRole
EmailAddress	String	Email address of the new user.

Request Example

The following SOAP XML example shows the parameters that you can pass to this call:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>

Code Block

language	java

Yellowfin

role

<orgId>1</orgId>

codes

can

found

performing

this

query

against

   <function>ADDUSER</

function>

Yellowfin

configuration

database:

SELECT

FROM

OrgRole ap.setPassword("test");


            <person>

<userId>binish.sheikh@yellowfin.com.au</userId>

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:

Code Block

language	java

rsr.setPerson(ap);

Once the request is configured, carry out the call:

Code Block

language	java

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

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:

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

Code Block

language	java

<%<emailAddress>binish.sheikh@yellowfin.com.au</emailAddress>
                <password>admin</password>
                <firstName>Binish</firstName>
 	            <lastName>Sheikh</lastName>
                <roleCode>YFREPORTCONSUMER</roleCode>
            
</*person>           
   ws_adduser.jsp      </arg0>
      </web:remoteAdministrationCall>
      */
%>


<%@ 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");</soapenv:Body>
</soapenv:Envelope>

Reponse Parameters

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

Reponse Example

The service will return the below response, according to our SOAP example:

Code Block

language	xml

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0</errorCode>
            <messages>Successfully Authenticated User: // provide your Yellowfin webservices admin account
rsr.setPassword("test");admin@yellowfin.com.au</messages>
            <messages>Creating New User via Webservices...</messages>
            <messages>Creating SessionBean for webservices  // 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");    user...</messages>
            <messages>Looking up user...</messages>
            <messages>Web Service Request Complete</messages>
            <sessionId>8090cb7879f7d5e72eab9625772c00b5<//sessionId>
  Yellowfin role codes can be found performing this query against 
												<statusCode>SUCCESS</statusCode>
   // Yellowfin configuration database: SELECT * FROM OrgRole

ap.setPassword("test"); </return>
      </ns2:remoteAdministrationCallResponse>
               	   // Password must comply with your Yellowfin password policy 
ap.setEmailAddress("john.smith@yellowfin.</S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Here's a basic request to create a new Yellowfin user, which includes logging in as the admin user and specifying the web service call to perform:
Code Block
language java
AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.

setPerson

setPassword(

"test");

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr

rsr.setOrgId(1);

rsr.setFunction("

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

...

ADDUSER");

If you need to create a new user in a specific client organization, add this to your code
Code Block
language java
rsr.setOrgRef("org1"); // A new user will be added to the client org 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:
Code Block
language java
AdministrationPerson ap = new AdministrationPerson();

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

Code Block

language	java

ap.setUserId("john.smith@yellowfin.com.au");		// if Yellowfin authentication option is set to "email address"
ap.setFirstName("John");
ap.setLastName("Smith");
ap.setRoleCode("YFREPORTCONSUMER");

...

Expand

title	ADDUSERS

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:

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

Code Block

language	java

<% /*

ws_addusers.jsp

  // Yellowfin role codes can be found performing this query

*/ %> <%@ 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);

against 
												   // Yellowfin configuration database: SELECT * FROM OrgRole

ap.setPassword("test");                    		   //

adjust

Password

host

must

and

comply

port number AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService(); AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin

with your Yellowfin password policy
ap.setEmailAddress("john.smith@yellowfin.com.au");

Other parameters of the AdministrationPerson object are optional.

Pass the 'ap' object to the request:
Code Block
language java
rsr.setPerson(ap);

Once the request is configured, carry out the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

The response returned will contain the StatusCode parameter. See the Response Parameters table above for details.

Complete Example

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

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

Code Block

language	java

<%            
/*          // 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");                 ws_adduser.jsp                
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"*/
%>


<%@ 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 web service admin account
ap[1].setEmailAddress("user2@yellowfin.com.au");


rsr.setPeople(aprsr.setPassword("test");                           // change this to the password of the above account
rsr.setOrgId(1);
rsr.setFunction("ADDUSER");


AdministrationServiceResponseAdministrationPerson rsap = new adminService.remoteAdministrationCallAdministrationPerson(rsr);

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

...

title	ADDUSERSIGNOREDUPLICATES

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.

...

Code Block

language	java

rsr.setFunction("ADDUSERSIGNOREDUPLICATES");

...

Code Block

language	java

AdministrationPerson[] failed_users = rs.getPeople();

...

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.

john.smith@yellowfin.com.au"); 		// If Yellowfin authentication option is set to "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());
}
%>

Anchor

	addusers
	addusers

Expand

title	ADDUSERS

This function creates users in bulk. It is similar to the ADDUSER function, however this requires that you pass an array of AdministrationPerson objects.

Request Parameters

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "ADDUSERS".
Person	AdministrationPerson[]	Object array containing details of the new users to be added in bulk. See table below.
OrgRef	String	Client Org Internal Reference Id (optional). This will create the new users in the referenced Client Org. If this is not set, then the users will be created in default (primary) org.

Anchor

	addusersap
	addusersap

These are the mandatory parameters that you need to set in the AdministrationPerson object to create a new user:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the new user. This can be the user ID or the email address, depending on the Logon ID method.
Password	String	Password of the new user. This must comply with Yellowfin's Password Policy.
FirstName	String	The first name of the new user.
LastName	String	The last name of the new user.
RoleCode	String	Set the user role for this new user. For example, YFREPORTCONSUMER. Note: You can get a list of Yellowfin's role codes from the configured database, for example, by using a SQL query: SELECT * FROM OrgRole
EmailAddress	String	Email address of the new user.

Reponse Parameters

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

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Here's a basic request to create new Yellowfin users, which includes logging in as the admin user and specifying the web service call to perform:

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();


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

rsr.setFunction("ADDUSERS");

If you need to create new users in a specific client organization, add this to your code:
Code Block
language java
rsr.setOrgRef("org1");
If you do not define the orgRef parameter, the new users will be created in the default (primary) organization.

Use AdministrationPerson object to define the new Yellowfin users details:
Code Block
language java
AdministrationPerson[] ap = new AdministrationPerson[2];

Add details of the first user by providing these mandatory parameters: UserId, FirstName, LastName, RoleCode, Password, EmailAddress:

Code Block

language	java

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");

Other parameters of the AdministrationPerson object are optional.

Similary, provide the mandatory details of the other user:

Code Block

language	java

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");

This can be repeated for as many users as required.

Pass the 'ap' object to the request:
Code Block
language java
rsr.setPeople(ap);

Once the request is configured, carry out the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

The response returned will contain the StatusCode parameter. See the Response Parameters table above for details.

Complete Example

Below is a complete example of the ADDUSERS 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:

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

Code Block

language	java

<%            
/*              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 web services admin account
rsr.setPassword("test");                           // change to the password of the above account
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() );
}
%>

Anchor

	addusersignoreduplicates
	addusersignoreduplicates

Expand

title	ADDUSERSIGNOREDUPLICATES

This function allows multiple users to be created, without adding duplicates. It works similarly 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 objects with failed users that were not added.

Request Parameters

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "ADDUSERSIGNOREDUPLICATES".
Person	AdministrationPerson[]	Object array containing details of the new users to be added and validated for duplicates. See table below.
OrgRef	String	Client Org Internal Reference Id (optional). This will create the new users in the referenced Client Org. If this is not set, then the users will be created in default (primary) org.

Anchor

	addusernodupsap
	addusernodupsap

These are the mandatory parameters that you need to set in the AdministrationPerson object to create a new user:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the new user. This can be the user ID or the email address, depending on the Logon ID method.
Password	String	Password of the new user. This must comply with Yellowfin's Password Policy.
FirstName	String	The first name of the new user.
LastName	String	The last name of the new user.
RoleCode	String	Set the user role for this new user. For example, YFREPORTCONSUMER. Note: You can get a list of Yellowfin's role codes from the configured database, for example, by using a SQL query: SELECT * FROM OrgRole
EmailAddress	String	Email address of the new user.

Reponse Parameters

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

AdministrationPerson[]

Failed users whose accounts were not created.

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Here's a basic request to create new Yellowfin users, which includes logging in as the admin user and specifying the web service call to perform:

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();


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

rsr.setFunction("ADDUSERSIGNOREDUPLICATES");

If you need to create new users in a specific client organization, add this to your code:
Code Block
language java
rsr.setOrgRef("org1");
If you do not define the orgRef parameter, the new users will be created in the default (primary) organization.

Use AdministrationPerson object to define the new Yellowfin users details:
Code Block
language java
AdministrationPerson[] ap = new AdministrationPerson[2];

Add details of the first user by providing these mandatory parameters: UserId, FirstName, LastName, RoleCode, Password, EmailAddress:

Code Block

language	java

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");

Other parameters of the AdministrationPerson object are optional.

Similary, provide the mandatory details of the other user:

Code Block

language	java

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");

This can be repeated for as many users as required.

Pass the 'ap' object to the request:
Code Block
language java
rsr.setPeople(ap);

Once the request is configured, carry out the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

The response returned will contain the StatusCode and People parameters. See the Response Parameters table above for details.

Use this command to retrieve failed users:
Code Block
language java
AdministrationPerson[] failed_users = rs.getPeople();

Anchor

	deleteuser
	deleteuser

Expand

title	DELUSER / DELETEUSER

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

Request Elements

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "DELETEUSER" or "DELUSER".
Person	AdministrationPerson	Object containing details of the user account that needs to be deleted. Note: See table below.
OrgRef	String	Client Org Internal Reference Id (optional). This will log the user into a given Client Org. If this is not set, then the user will be prompted with the Client Org Selection page on login.

Anchor

	deluserap
	deluserap

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

AdministrationPerson Element

Data Type

Description

UserId

String

User ID of the user that you wish to delete. This user should already exist in Yellowfin.

This value could be a user ID or an email address, depending on the Logon ID method.

Request Example

The following SOAP example shows the parameters that you can pass to this call:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>DELETEUSER</function>        
            <person>
            	<userId>binish.sheikh@yellowfin.com.au</userId>
            </person>          
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Reponse Elements

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

Response Example

The service will return the below response, according to our SOAP example:

Code Block

language	xml

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0</errorCode>
            <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Web Service Request Complete</messages>
            <sessionId>cc8c2b81d06485fdd20fe4cd24f5f70c</sessionId>
            <statusCode>SUCCESS</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Here is a basic request for this call, which includes logging in as the admin user and specifying the web service call to perform.

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("DELETEUSER");

The function requires an AdministrationPerson object, which is used to specify which user to delete, by providing their ID (for example, their email address or another type of ID depending on the Login ID method):

Code Block

language	java

AdministrationPerson ap = new AdministrationPerson();

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

After configuring the request, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Then initialize the Administration web service. Click here to learn how to do this.

The response will contain the StatusCode parameter. See the Response Parameters table above for more detail.

Complete Example

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

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

Code Block

language	java

<%            
/*              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 web services admin account
rsr.setPassword("test");                           // change to the password of the above account
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() );
}
%>

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.

Anchor

	getuser
	getuser

Expand

title	GETUSER

This function retrieves an existing Yellowfin user's details. It accepts AdministrationPerson as a parameter which you can use to identify the user. The response will contain the AdministrationPerson object with full user details.

Request Elements

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	The ID of a web services admin user who logs in to perform this function. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "GETUSER".
Person	AdministrationPerson	Object containing details of the user whose information is to be retrieved. Note: See table below.
OrgRef	String	Client Org Internal Reference Id (optional). This will log the user into a given Client Org. If this is not set, then the user will be prompted with the Client Org Selection page on login.

Anchor

	getuserap
	getuserap

These are the main parameters that you need to set in the AdministrationPerson object for this function:

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

Request Example

The following SOAP example shows the parameters that you can pass to this call:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>GETUSER</function>        
            <person>
            	<userId>admin@yellowfin.com.au</userId>
            </person>          
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Reponse Elements

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

Object with the user details

Reponse Example

The service will return the below response, according to our SOAP example:

Code Block

language	xml

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0</errorCode>
            <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Getting user information...</messages>
            <messages>Getting user information...</messages>
            <messages>Web Service Request Complete</messages>
            <person>
               <emailAddress>admin@yellowfin.com.au</emailAddress>
               <firstName>System</firstName>
               <initial/>
               <ipId>5</ipId>
               <languageCode>EN</languageCode>
               <lastName>Administrator</lastName>
               <roleCode>YFADMIN</roleCode>
               <salutationCode/>
               <status>ACTIVE</status>
               <timeZoneCode>AUSTRALIA/SYDNEY</timeZoneCode>
               <userId>admin@yellowfin.com.au</userId>
            </person>
            <sessionId>70dc3c7158a340e19b590f0ed6ea6a8b</sessionId>
            <statusCode>SUCCESS</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Following is a basic request for this call, which includes logging in as the admin user and specifying the web service call to perform:

Code Block

language	java

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:

Code Block

language	java

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

Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

The response will contain the StatusCode and Person parameters. See the Response Parameters table for details.

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

Code Block

language	java

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:

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

Code Block

language	java

<%            
/*              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 web services admin account
rsr.setPassword("test");                           // change to the password of the above account
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() );
}
%>

Anchor

	getallusers
	getallusers

Expand

title	GETALLUSERS

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.

Request Elements

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	The ID of a web services admin user who logs in to perform this function. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "GETUSER".
OrgRef	String	Client Org Internal Reference Id (optional). Specify a client organization, otherwise all the client organizations will get searched.
Client	AdministrationClientOrg	(Optional.) Setting the required properties on this object specifies a Client Org to be searched; otherwise, all the client organizations will get searched if not passed. See table below.

AdministrationClientOrg Element	Data Type	Description
ClientReferenceID	String	Client Org Internal Reference Id to be searched.

Request Example

The following SOAP example shows the parameters that you can pass to this call:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>GETALLUSERS</function>
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Response Elements

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

AdministrationPerson[]

Array of objects with the users’ details.

Response Example

The service will return the below response, according to our SOAP example:

Code Block

language	xml

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0</errorCode>
            <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Web Service Request Complete</messages>
            <people>
               <firstName>System</firstName>
               <ipId>5</ipId>
               <lastName>Administrator</lastName>
               <userId>admin@yellowfin.com.au</userId>
            </people>
            <sessionId>2c32528279baa26b730f9e3c8787880d</sessionId>
            <statusCode>SUCCESS</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Here's an example of a request to retrieve all users, which includes logging in as the admin user:

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

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

Code Block

language	java

AdministrationClientOrg client = new AdministrationClientOrg();
client.setClientReferenceId("org1");
rsr.setClient(client);

Call the function:
Code Block
language java
rsr.setFunction("GETALLUSERS");
Searching Criteria: The GETALLUSERS function accepts an array of two 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.
Code Block
language xml
String[] searchingCriteria = new String[] {"John","yellowfin.com.au"}; rsr.setParameters(searchingCriteria);

Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

The response will contain the StatusCode and People parameters. See the Response Parameters table above for more details.

Complete Example

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

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

Code Block

language	java

<%            
/*              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);

AdministrationClientOrg client = new AdministrationClientOrg();
client.setClientReferenceId("org1");
rsr.setClient(client);
 
rsr.setFunction("GETALLUSERS");

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() );
}
%>

Anchor

	getuserbyip
	getuserbyip

Expand

title	GETUSERBYIP

This function will retrieve details of a user by their IP. It accepts the AdministrationPerson object as a parameter, which can be used to identify the user, by providing their IPID (in the Yellowfin configuration database, this is the IpId field of the Person table). The response will contain the AdministrationPerson object with the full details of the user.

Request Elements

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	The ID of a web services admin user who logs in to perform this function. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "GETUSERBYIP".
Person	AdministrationPerson	Object containing details of the user whose information is to be retrieved. Note: See table below.

Anchor

	getuseripap
	getuseripap

Following is the main parameter that you need to set in the AdministrationPerson object for this function:

AdministrationPerson Element	Data Type	Description
IpId	Integer	IP ID of the user whose information is to be retrieved.

Request Example

The following SOAP example shows the parameters that you can pass to this call:

Code Block

language	xml

 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>GETUSERBYIP</function>
		  <person>
                <ipId>5</ipId>
            </person>
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Reponse Elements

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

Object with the user details

Reponse Example

The service will return the below response, according to our SOAP example:

Code Block

language	xml

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0</errorCode>
            <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Getting user information...</messages>
            <messages>Getting user information...</messages>
            <messages>Web Service Request Complete</messages>
            <person>
               <emailAddress>admin@yellowfin.com.au</emailAddress>
               <firstName>System</firstName>
               <initial/>
               <ipId>5</ipId>
               <languageCode>EN</languageCode>
               <lastName>Administrator</lastName>
               <roleCode>YFADMIN</roleCode>
               <salutationCode/>
               <status>ACTIVE</status>
               <timeZoneCode>AUSTRALIA/SYDNEY</timeZoneCode>
               <userId>admin@yellowfin.com.au</userId>
            </person>
            <sessionId>81e76f1222d0dd12d9871efc7cbf0811</sessionId>
            <statusCode>SUCCESS</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Here is a basic request for this call, which includes logging in as the admin user and specifying the web service call to perform:

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("GETUSERBYIP");

Then use the AdministrationPerson object to identify the user whose details are to be retrieved, by providing their IpId:

Code Block

language	java

AdministrationPerson ap = new AdministrationPerson();

ap.setIpId(5);                  //IpId of the admin@yellowfin.com.au account
rsr.setPerson(ap);

Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

This call's response will contain thes StatusCode and Person parameters. See the Response Parameters table above for more details.

Use this example to display the result of this call:

Code Block

language	java

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 GETUSERBYIP function. To use it for yourself, first carry out the following the steps:

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

Code Block

language	java

<%            
/*              ws_getuserbyip.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 web services admin account
rsr.setPassword("test");                           // change to the password of the above account
rsr.setOrgId(1);
rsr.setFunction("GETUSERBYIP");

AdministrationPerson ap = new AdministrationPerson();

ap.setIpId(5);
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() );
}
%>

Anchor

	getavatars
	getavatars

Expand

title	GETAVATARS

This web service is used to retrieve users' avatar images. If an avatar image is not set up for a user in Yellowfin, then no image will be retrieved for that user. This service requires the users' internal IDs (that is, their IP ID).

Request Parameters

The following parameters should be passed with this request:

Request Element	Data Type	Description
LoginId	String	An admin account to connect to Yellowfin web services. This can be the user ID or the email address, depending on the Logon ID method. This account must have the “web services” role enabled, and must belong to the default (i.e. primary) org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web service function. Set this to "GETAVATARS".
Parameters	String[]	An array containing the internal IDs (or IpId) of Yellowfin users’ whose avatars you want to retrieve. Each ID must be passed as a String, even though it's an Integer.

Request Example

Below is a SOAP XML example for this request:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
 	       <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>GETAVATARS</function>
            <parameters>5</parameters>
         </arg0>
  	</web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Response Parameters

The returned response will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

binaryAttachments

ReportBinaryObject[]

Contains avatar images for the specified users.

Response Example

The service will return the below response, according to our SOAP example:

Code Block

language	xml

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <binaryAttachments>
               <data>iVBORw0KGgoAAAANSUhEUgAAA ... your image string</data>
            </binaryAttachments>
            <errorCode>0</errorCode>
            <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Web Service Request Complete</messages>
            <sessionId>5547ebe153fd0fc7fcf63014ffe61b5c</sessionId>
            <statusCode>SUCCESS</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Start with a basic request for this function, which includes logging in as the admin user and specifying the web service call to perform:

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("GETAVATARS");

You can specify the users' IP IDs:
Code Block
language java
rsr.setParameters(new String[] {"5","13073"});

Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

The response will contain a StatusCode element, along with a BinaryAttachment array.
To get the first image, use the following:
Code Block
language java
byte[] data = response.getBinaryAttachments[0].getData();

Complete Example

Below is a full example of this web service call. To use it for yourself, carry out the following the steps:

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

Code Block

language	java
theme	Eclipse

<%            
/*              ws_getavatars.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.*" %>
<html>
<body>
<%
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 web services admin account
rsr.setPassword("test");                           // set to the password of the above account
rsr.setOrgId(1);

rsr.setFunction("GETAVATARS");
rsr.setParameters(new String[] {"5","13073"});
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

if ("SUCCESS".equals(rs.getStatusCode()) ) {
	ReportBinaryObject[] objects = rs.getBinaryAttachments();
	if (objects != null) {
		byte[] data,encodeBase64;
		String base64Encoded;

		for(ReportBinaryObject o: objects){
			data = o.getData();
			if (data != null){

				encodeBase64 = java.util.Base64.getEncoder().encode(data);
				base64Encoded = new String(encodeBase64, "UTF-8");
				if (base64Encoded != null)  
					out.write("<br>");
				%>
				<img src="data:image/jpg;base64,<%=base64Encoded%>" alt="No image">
				<%
			}
		}
	}
} else {
	out.write("Failure");
	out.write(" Code: " + rs.getErrorCode());
}
%>
</body>
</html>

Anchor

	validateuser
	validateuser

Expand

title	VALIDATEUSER

This function validates a Yellowfin user. You can specify the user by using the AdministrationPerson as a parameter.

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

Request Elements

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	The ID of a web services admin user who logs in to perform this function. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "VALIDATEUSER".
Person	AdministrationPerson	Object containing details of the user who is to be validated. Note: See table below.
OrgRef	String	Client organization reference ID (optional). Provide this if you need to validate the user of a specific organization.

Anchor

	validateuserap
	validateuserap

These are the main parameters that you need to set in the AdministrationPerson object for this function:

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

Request Example

The following SOAP example shows the parameters that you can pass to this call:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>VALIDATEUSER</function>
		  <person>
                <userId>admin@yellowfin.com.au</userId>
                <password>test</password>
            </person>
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Reponse Elements

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

Object with the user details.

Reponse Example

The service will return the below response, according to our SOAP example:

Code Block

language	xml

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0</errorCode>
            <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Web Service Request Complete</messages>
            <person>
               <ipId>5</ipId>
               <userId>admin@yellowfin.com.au</userId>
            </person>
            <sessionId>0ee8ae23d21ff01f365d1e03ea49c47a</sessionId>
            <statusCode>SUCCESS</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Here's an example of a basic request to call this function, which includes logging in as the admin user and specifying the web service call to perform:

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("VALIDATEUSER");

Now you need to provide user ID via the AdministrationPerson object:

Code Block

language	java

AdministrationPerson ap = new AdministrationPerson();

ap.setUserId("john.smith@yellowfin.com.au");
ap.setPassword("test");

rsr.setPerson(ap);

You can provide a client organization reference ID if you need to validate the user of a specific organization:
Code Block
language java
rsr.setOrgRef("org1");
If the OrgRef parameter is omitted, the user will be validated against the default (primary) organization.

Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.
The response will contain the StatusCode parameter.

Complete Example

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

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

Code Block

language	java

<%            
/*              ws_validateuser.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 web services admin account
rsr.setPassword("test");                           // change to the password of the above account
rsr.setOrgId(1);
rsr.setFunction("VALIDATEUSER");

AdministrationPerson ap = new AdministrationPerson();

ap.setUserId("john.smith@yellowfin.com.au");
ap.setPassword("test");

rsr.setPerson(ap);
rsr.setOrgRef("org1");

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

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

Anchor

	validatepassword
	validatepassword

Expand

title	VALIDATEPASSWORD

This call validates a user's password. If the password is expired, the call will return SUCCESS as the StatusCode, otherwise it will return FAILURE.

Keep in mind that for a freshly created user who has not yet logged into Yellowfin, the call retrieves SUCCESS meaning that their password is expired. This happens because for every new user, Yellowfin is required to reset the password at the first login.

Request Elements

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "VALIDATEPASSWORD".
Person	AdministrationPerson	Object containing details of user whose password is to be validated. See table below.

Anchor

	valpassap
	valpassap

These are the mandatory parameters that you need to set in the AdministrationPerson object for this function:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the user whose password is to be validated. This can be the user ID or the email address, depending on the Logon ID method.
Password	String	Password of the above account.

Request Example

The following SOAP example shows the parameters that you can pass to this call:

Code Block

language	xml

 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>VALIDATEPASSWORD</function>
		 	<person>
                <userId>admin@yellowfin.com.au</userId>
                <password>test</password>
            </person>
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Reponse Elements

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

Reponse Example

The service will return the below response, according to our SOAP example:

Code Block

language	xml

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0</errorCode>
            <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Web Service Request Complete</messages>
            <sessionId>fb024963bdc94034557f95b01f53a138</sessionId>
            <statusCode>FAILURE</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

...

Status of the web service call. Possible values include:

SUCCESS

FAILURE

Expand

title	DELUSER / DELETEUSER

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

Expand

title	Step-by-step instructions

Here is a basic example of this request, which includes logging in as the admin user and specifying the web service call to perform:

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("

DELETEUSER

VALIDATEPASSWORD");

The function requires AdministrationPerson object, which is used to specify which user to delete by providing their ID (for example, their email address or another type of ID depending on the Login ID method)

Then provide the user ID via the AdministrationPerson object:
Code Block
language java
AdministrationPerson ap = new AdministrationPerson();

ap.setUserId("

test@yellowfin

john.smith@yellowfin.com.au");

// test@yellowfin.com.au should be existing Yellowfin user.


ap.setPassword("test");

rsr.setPerson(ap);

After configuring

Once the request is configured, perform the call:

Code Block

language	java

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

Then initialize

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

the StatusCode parameter. See the Response Parameters table above for more details.

Complete Example

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

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

Code Block

language	java

<%            
/*              ws_deleteuservalidatepwd.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 webservicesweb services 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() );
}
%>

...

// change to the password of the above account
rsr.setOrgId(1);
rsr.setFunction("VALIDATEPASSWORD");

AdministrationPerson ap = new AdministrationPerson();

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

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
if ("SUCCESS".equals(rs.getStatusCode()) ) {
	out.write("Password is expired");
} else {
	out.write("Failure");
	out.write(" Code: " + rs.getErrorCode() );
}
%>

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. .

Anchor

	changepassword
	changepassword

Expand

title	CHANGEPASSWORD

This function will change the password for the specified Yellowfin user. The password will be reset through the AdministrationPerson parameter, based on their user ID (email address or another type of ID depending on the Login ID method).

Request Elements

The following elements will be passed with this request:

Request Element	Data Type	Description
LoginId	String	Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method. This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password	String	Password of the above account.
OrgId	Integer	Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function	String	Web services function. Set this to "CHANGEPASSWORD".
Person	AdministrationPerson	Object containing details of the user whose password is to be changed. See table below.

Anchor

	changepassap
	changepassap

These are the mandatory parameters that you need to set in the AdministrationPerson object for this function:

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the user whose password is to be changed. This can be the user ID or the email address, depending on the Logon ID method.
Password	String	The new password of the user. This must comply with Yellowfin's Password Policy.

Request Example

The following SOAP example shows the parameters that you can pass to this call:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>CHANGEPASSWORD</function>
		  	<person>
                <userId>admin@yellowfin.com.au</userId>
                <password>test321</password>
            </person>
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Reponse Elements

The response returned will contain these

...

Reponse Example

The service will return the below response, according to our SOAP

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

Expand

title	GETUSER

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:

Code Block

language	java

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:

Code Block

language	java

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

Once the request is configured, perform the call:

Code Block

language	java

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

Code Block

language

java
if ("SUCCESS".equals(rs.getStatusCode()) ) { ap = rs.getPerson(); out.write("UserId:" + ap.getUserId() + " "); out.write("Password:" + ap.getPassword() + " "); out.write("FirstName:" + ap.getFirstName() + " "); out.write("LastName:" + ap.getLastName() + " "); out.write("Initial:" + ap.getInitial() + " "); out.write("SalutationCode:" + ap.getSalutationCode() + " "); out.write("RoleCode:" + ap.getRoleCode() + " "); out.write("EmailAddress:" + ap.getEmailAddress() + " "); out.write("LanguageCode:" + ap.getLanguageCode() + " "); out.write("IpId:" + ap.getIpId() + " "); out.write("TimeZoneCode:" + ap.getTimeZoneCode() + " "); out.write("Status:" + ap.getStatus() + " "); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode()); }
xml
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/"> <return> <errorCode>0</errorCode> <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages> <messages>Web Service Request Complete</messages> <sessionId>f6bdc33348cd76d7898f3bed3e54ff31</sessionId> <statusCode>SUCCESS</statusCode> </return> </ns2:remoteAdministrationCallResponse> </S:Body> </S:Envelope>

Instructions
See below for step-by-step instructions on how to perform this call, using a Java example:
Expand
title Step-by-step instructions

This example shows a basic request for this call, which includes logging in as the admin user and specifying the web service call to perform:

Code Block
language java
AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.setPassword("test"); rsr.setOrgId(1); rsr.setFunction("CHANGEPASSWORD");

Specify the user using the AdministrationPerson object:

Code Block
language java
AdministrationPerson ap = new AdministrationPerson(); ap.setUserId("john.smith@yellowfin.com.au"); ap.setPassword("test123"); rsr.setPerson(ap);

Once the request is configured, perform the call:

Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

The response will contain the StatusCode parameters. See the Response Parameters table above for details.

Complete Example
Complete Example
Below is a complete example of the GETUSER CHANGEPASSWORD function. To use it for yourself, carry out the following the steps:
Copy the code and save it as ws_getuserchangepwd.jsp.
Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
Adjust the host, port, admin user and user to get /new password details according to your environment.
Run http://<host>:<port>/ws_getuserchangepwd.jsp from your Internet browser.

Code Block
language java
<% /* ws_changepwd.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 = ws_getuser.jsp (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService(); AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); */ %> <%@ 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); provide your Yellowfin web services admin account rsr.setPassword("test"); // adjustchange hostto andthe port number AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService(); AdministrationServiceRequest rsrpassword of the above account rsr.setOrgId(1); rsr.setFunction("CHANGEPASSWORD"); AdministrationPerson ap = new AdministrationServiceRequestAdministrationPerson(); rsrap.setLoginIdsetUserId("admin@yellowfinjohn.smith@yellowfin.com.au"); ap.setPassword("test123"); rsr.setPerson(ap); AdministrationServiceResponse rs = // 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() + " "); out.write("Password:" + ap.getPassword() + " "); out.write("First Name:" + ap.getFirstName() + " "); out.write("Last Name:" + ap.getLastName() + " "); out.write("Initial:" + ap.getInitial() + " "); out.write("Salutation Code:" + ap.getSalutationCode() + " "); out.write("Role Code:" + ap.getRoleCode() + " "); out.write("Email Address:" + ap.getEmailAddress() + " "); out.write("Language Code:" + ap.getLanguageCode() + " "); out.write("IpId:" + ap.getIpId() + " "); out.write("Time Zone Code:" + ap.getTimeZoneCode() + " "); out.write("Status:" + ap.getStatus() + " "); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); } %>

...
adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { out.write("Password is reset"); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); } %>

Anchor
resetpasswd
resetpasswd
Expand
title RESETPASSWD
This function resets a user's Yellowfin account and prompts them to change their password. This call will not change the password of the account itself. To change the password, use the CHANGEPASSWORD function.

Request Elements
The following elements will be passed with this request:
Request Element
Data Type
Description
LoginId
String
Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method.
This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password
String
Password of the above account.
OrgId
Integer
Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function
String
Web services function. Set this to "RESETPASSWD".
Person
AdministrationPerson
Object containing details of the user whose password has to be reset. See table below.
Anchor
resetpassap
resetpassap
These are the mandatory parameters that you need to set in the AdministrationPerson object for this function:
AdministrationPerson Element
Data Type
Description
UserId
String
User ID of the user whose password is to be reset. This can be the user ID or the email address, depending on the Logon ID method.
Password
String
Password of the above account.

Request Example
The following SOAP example shows the parameters that you can pass to this call:
Code Block
language xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/"> <soapenv:Header/> <soapenv:Body> <web:remoteAdministrationCall> <arg0> <loginId>admin@yellowfin.com.au</loginId> <password>test321</password> <orgId>1</orgId> <function>RESETPASSWD</function> <person> <userId>admin@yellowfin.com.au</userId> <password>test321</password>
...
AdministrationPerson ap = new AdministrationPerson(); ap.setIpId(5);
Expand
title GETUSERBYIP
This function will retrieve details of a user by their IP. It accepts the AdministrationPerson object as a parameter, which can be used to identify the user, by providing their IPID (which in the Yellowfin configuration database is the IpId field of the Person table).
The response will contain the AdministrationPerson object with the full details of the user.

Here is what a basic request for this call:
Code Block
language java
AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.setPassword("test"); rsr.setOrgId(1); rsr.setFunction("GETUSERBYIP");
Then use the AdministrationPerson object to identify the user whose details are to be retrieved, by providing their IpId:
Code Block
language java
</person>
//IpId of admin@yellowfin.com.au account rsr.setPerson(ap);

Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.
</arg0> </web:remoteAdministrationCall> </soapenv:Body> </soapenv:Envelope>

Reponse Elements
The response returned

This call's response
will contain these 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

Request Example
The service will return the below response, according to our SOAP example:
Code Block
language xml
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/"> <return> <errorCode>0</errorCode> <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages> <messages>Web Service Request Complete</messages> <sessionId>beabd94a9ffaa562a8b9ba823fc291a0</sessionId> <statusCode>SUCCESS</statusCode> </return> </ns2:remoteAdministrationCallResponse> </S:Body> </S:Envelope>

Instructions
See below for step-by-step instructions on how to perform this call, using a Java example:

Expand
title Step-by-step instructions

Here is what a basic request for this call looks like, which includes logging in as the admin user and specifying the web service call to perform:

Code Block
language java
AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.setPassword("test"); rsr.setOrgId(1); rsr.setFunction("RESETPASSWD");

Use the AdministrationPerson object to identify the user whose account is to be reset:

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

Once the request is configured, perform the call:

Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

This call's response will contain the StatusCode parameter. See the Response Parameters table above for more details.

Use this example to display the result of this call:
Code Block
language java
if ("SUCCESS".equals(rs.getStatusCode()) ) { ap = rs.getPerson(); out.write("UserId: " + ap.getUserId() + " "); out.write("Password: " + ap.getPassword() + " "); out.write("FirstName: " + ap.getFirstName() + " "); out.write("LastName: " + ap.getLastName() + " "); out.write("Initial: " + ap.getInitial() + " "); out.write("SalutationCode: " + ap.getSalutationCode() + " "); out.write("RoleCode: " + ap.getRoleCode() + " "); out.write("EmailAddress: " + ap.getEmailAddress() + " "); out.write("LanguageCode: " + ap.getLanguageCode() + " "); out.write("IpId: " + ap.getIpId() + " "); out.write("TimeZoneCode: " + ap.getTimeZoneCode() + " "); out.write("Status: " + ap.getStatus() + " "); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode()); }

Complete Example
Below is a complete example of the GETUSERBYIP RESETPASSWD function. To use it for yourself, first carry out the following the steps:
Copy the code and save it as ws_getuserbyipresetpwd.jsp.
Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
Adjust the host, port, admin user and user IpId to reset according to your environment.
Run http://<host>:<port>/ws_getuserbyipresetpwd.jsp from your Internet browser.

Code Block
language java
<% /* ws_getuserbyip resetpwd.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 web webservicesservices admin account rsr.setPassword("test"); // change to be the password of the account above rsr.setOrgId(1); rsr.setFunction("GETUSERBYIP"); AdministrationPerson ap = new AdministrationPerson(); ap.setIpId(5); rsr.setPerson(ap); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { ap = rs.getPerson(); out.write("User Id: " + ap.getUserId() + " "); out.write("Password: " + ap.getPassword() + " "); out.write("First Name: " + ap.getFirstName() + " "); out.write("Last Name: " + ap.getLastName() + " "); out.write("Initial: " + ap.getInitial() + " "); out.write("Salutation Code: " + ap.getSalutationCode() + " "); // change to the password of the account above rsr.setOrgId(1); rsr.setFunction("RESETPASSWD"); AdministrationPerson ap = new AdministrationPerson(); ap.setUserId("john.smith@yellowfin.com.au"); rsr.setPerson(ap); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { out.write("RoleAccount Code:is reset"); } + ap.getRoleCode() + " else { out.write("Failure"); out.write("Email AddressCode: " + aprs.getEmailAddressgetErrorCode() + " "); out.write("Language Code: " + ap.getLanguageCode() + " "); out.write("IpId: " + ap.getIpId() + " "); out.write("Time Zone Code: " + ap.getTimeZoneCode() + " "); out.write("Status: " + ap.getStatus() + " "); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); } %>

...
} %>

Anchor
updateuser
updateuser
Expand
title UPDATEUSER
This call will edit a user’s details. It accepts AdministrationPerson as a parameter, which can be used to identify the user, by providing their ID (for example, their email address, or another type of ID depending on the Logon ID method).
The response will contain the AdministrationPerson object with the full details of the user.
Note: This call will not change the password of the user's account. To change the password, use the CHANGEPASSWORD function.

Request Elements
The following elements will be passed with this request:
Request Element
Data Type
Description
LoginId
String
User ID of the Yellowfin web services administrator who calls this web service. This can be the user ID or the email address, depending on the Logon ID method.
This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password
String
Password of the above account.
OrgId
Integer
Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function
String
Web services function. Set this to "UPDATEUSER".
Person
AdministrationPerson
Object containing user details that need to be updated. See table below.
Anchor
updateuserap
updateuserap
Mandatory parameters to set in the AdministrationPerson object for this function:
AdministrationPerson Element
Data Type
Description
UserId
String
User ID to identify the user whose details are to be changed. This can be the user ID or the email address, depending on the Logon ID method.
You can provide any other parameters related to the user detail that needs to be updated. For example, a new FirstName to change their name, or Status to update their status, etc.

Request Example
The following SOAP example shows the parameters that you can pass to this call. This example shows the user's status being changed to "Inactive":
Code Block
language xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/"> <soapenv:Header/> <soapenv:Body> <web:remoteAdministrationCall> <arg0> <loginId>admin@yellowfin.com.au</loginId> <password>test</password> <orgId>1</orgId> <function>UPDATEUSER</function> <person> <userId>binish.sheikh@yellowfin.com.au</userId> <status>ACTIVE</status> </person> </arg0> </web:remoteAdministrationCall> </soapenv:Body> </soapenv:Envelope>

Reponse Elements
The response returned will contain these
...
Expand
title GETALLUSERS

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:
Code Block
language java
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:
Code Block
language java
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:
Code Block
language java
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
Person
AdministrationPerson
[]
Array of objects
Object with the
users’
user details updated.
Complete Example
Below is a complete example of the GETALLUSERS function. To use it for yourself, carry out the following the steps:
Copy the code and save it as ws_getallusers.jsp.
Put the file in the Yellowfin/appserver/webapps/ROOT folder.
Adjust host, port, admin user and searching criteria according to your environment.
Run http://<host>:<port>/ws_getallusers.jsp from your Internet browser.

Response Example
The service will return the below response, according to our SOAP example:
Code Block
language xml
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/"> <return> <errorCode>0</errorCode> <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages> <messages>Getting user information...</messages> <messages>Getting user information...</messages> <messages>Web Service Request Complete</messages> <person> <emailAddress>binish.sheikh@yellowfin.com.au</emailAddress>
Code Block
language java
<% <firstName>Binish</firstName> /* ws_getallusers.jsp<ipId>13000</ipId> *<lastName>Sheikh</ %> <%@ 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);lastName> <roleCode>YFADMIN</roleCode> <status>ACTIVE</status> <timeZoneCode>AUSTRALIA/BRISBANE</timeZoneCode> adjust host and port number AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService(); AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin <userId>binish.sheikh@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() ); } %>

...
au</userId> </person> <sessionId>586e172a7c4850bb3edbaaf5264a312d</sessionId> <statusCode>SUCCESS</statusCode> </return> </ns2:remoteAdministrationCallResponse> </S:Body> </S:Envelope>

Instructions
See below for step-by-step instructions on how to perform this call, using a Java example:
Expand
title Step-by-step instructions

Here is what a basic request for this call will look like, which includes logging in as the admin user and specifying the web service call to perform
...
Expand
title VALIDATEUSER

This function validates a Yellowfin user. It accepts AdministrationPerson as a parameter where you can provide user ID (email address or another 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. Otherwise 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
:

Code Block
language java
AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.setPassword("test"); rsr.setOrgId(1); rsr.setFunction("
VALIDATEUSER
UPDATEUSER");
Now you need to provide user ID via

Then use the AdministrationPerson object to identify the user whose details are to be updated:

Code Block
language java
AdministrationPerson ap = new AdministrationPerson
(); ap.setUserId("john.smith@yellowfin.com.au"); ap.setPassword
(
"test"
);
rsr
ap.
setPerson(ap
setUserId("john.smith@yellowfin.com.au");
You can provide a client organization reference ID if you need to validate the user of a specific organization

Specify what detail is to be changed. For example, we can make a user account inactive:
Code Block
language java
rsr
ap.
setOrgRef
setStatus("
org1

INACTIVE");
If the OrgRef parameter is omitted, the user will be validated against the default (primary) organization.
// This shows that the user "john.smith@yellowfin.com.au" will not be able to log in rsr.setPerson(ap);

The
Once the request is configured, perform the call:

Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

This call's response will contain
these parameters:
Response Element
Data Type
Description
StatusCode
String
Status of the web service call. Possible values include:
SUCCESS
FAILURE
the StatusCode and Person parameters. See the Response Parameters table above for more details.

Complete Example
Below is a complete example of the VALIDATEUSER UPDATEUSER function. To use it for yourself, carry out the following the steps:
Copy the code and save it as ws_validateuserupdateuser.jsp.
Put the file in the root folder: Yellowfin/appserver/webapps/ROOT folder.
Adjust the host, port, admin user and user to validate update according to your environment.
Run http://<host>:<port>/ws_updateuser.jsp from your Internet browser.

Code Block
language java
<% /
ws_validateuser.jsp from your Internet browser.

Code Block
language java
<% /* ws_validateuser.jsp * ws_updateuser.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 */ %> <%@ 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);Yellowfin web services admin account rsr.setPassword("test"); // 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("VALIDATEUSER"); AdministrationPerson ap = new AdministrationPerson(); ap.setUserId("john.smith@yellowfin.com.au"); ap.setPassword("test"); rsr.setPerson(ap); rsr.setOrgRef("org1"); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { out.write("User is authenticated change to the password of the above account rsr.setOrgId(1); rsr.setFunction("UPDATEUSER"); AdministrationPerson ap = new AdministrationPerson(); ap.setUserId("john.smith@yellowfin.com.au"); ap.setStutus("INACTIVE"); rsr.setPerson(ap); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { ap = rs.getPerson(); out.write("User Id: " + ap.getUserId() + " "); out.write("Password: " + ap.getPassword() + " "); out.write("First Name: " + ap.getFirstName() + " "); out.write("Last Name: " + ap.getLastName() + " "); out.write("Initial: " + ap.getInitial() + " "); out.write("Salutation Code: " + ap.getSalutationCode() + " "); out.write("Role Code: " + ap.getRoleCode() + " "); out.write("Email Address: " + ap.getEmailAddress() + " "); out.write("Language Code: " + ap.getLanguageCode() + " "); out.write("IpId: " + ap.getIpId() + " "); out.write("Time Zone Code: " + ap.getTimeZoneCode() + " "); out.write("Status: " + ap.getStatus() + " "); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); } %>

Anchor
validatepasswordsetavatarimgvalidatepassword
setavatarimg
Expand
title VALIDATEPASSWORDSETAVATARIMAGE
This web service is used to upload an avatar image for a specified user. The image should be an array of bytes in UTF-8 which you could convert to a String value.

Request Parameters
The following parameters should be passed with this request:
Request Element
Data Type
Description
LoginId
String
An admin account to connect to Yellowfin web services. This can be the user ID or the email address, depending on the Logon ID method.
This account must have the “web services” role enabled, and must belong to the default (i.e. primary) org.
Password
String
Password of the above account.
OrgId
Integer
Default (i.e. primary) organization ID within Yellowfin. Always set this to 1.
Function
String
Web service function. Set this to "SETAVATARIMAGE".
Person AdministrationPerson This object contains details of the user whose avatar is to be changed. See table below.
Parameters String[] An array containing a single element representing the avatar image to be uploaded. The image should be an array of bytes in UTF-8 format, which could be converted to a String.
Anchor
setavatarap
setavatarap
These are the main parameters that you must set in the AdministrationPerson object for this web service call:
AdministrationPerson

This call validates a user's password. If the password is expired, the call will return SUCCESS as the StatusCode, otherwise it will return FAILURE. It accepts AdministrationPerson as a parameter where you can provide a user ID (email address or another ID depending on the Login ID method) and password to validate.
Keep in mind that for a freshly created user who has not yet logged into Yellowfin, the call retrieves SUCCESS meaning that their password is expired. This happens because for every new user, Yellowfin requires to reset the password at the first login.

Here is a basic example of this request:
Code Block
language java
AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.setPassword("test"); rsr.setOrgId(1); rsr.setFunction("VALIDATEPASSWORD");
Then provide the user ID via the AdministrationPerson object:
Code Block
language java
AdministrationPerson ap = new AdministrationPerson(); ap.setUserId("john.smith@yellowfin.com.au"); ap.setPassword("test"); rsr.setPerson(ap);
Once the request is configured, perform the call:
Code Block
language java
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
IpId
String
Status of the web service call. Possible values include:
SUCCESS
FAILURE
Integer
Provide the internal Yellowfin IP ID of the user. This value is stored in the Person parameter's IpId field in Yellowfin's database.

Request

Complete
Example
Below is a complete example of the VALIDATEPASSWORD function. To use it for yourself, carry out the following the steps:
Copy the code and save it as ws_validatepwd.jsp.
Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
Adjust the host, port, admin user and user to validate details according to your environment.
Run http://<host>:<port>/ws_validatepwd.jsp from your Internet browser

SOAP XML example for this request:
Code Block
language xml
theme Confluence
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/"> <soapenv:Header/> <soapenv:Body> <web:remoteAdministrationCall> <arg0> <loginId>admin@yellowfin.com.au</loginId> <password>test</password>
Code Block
language java
<% <orgId>1</orgId> /* <function>SETAVATARIMAGE</function> ws_validatepwd.jsp <person> * <ipId>5</ %> <%@ 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);ipId> </person> <parameters> <string>iVBORw0KGgoAAAANSUhEUgAAAdsAAA ... your image string</string> <//parameters> adjust host and port number AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService(); AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); </arg0> </web:remoteAdministrationCall> </soapenv:Body> </soapenv:Envelope>

Response Parameters
The returned response will contain the following parameter:
Response Element
Data Type
Description
StatusCode
String
Status of the web service call. Possible values include:
SUCCESS
FAILURE

Response Example
The service will return the below response, according to our SOAP example:
Code Block
language xml
theme Confluence
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/ provide your Yellowfin webservices admin account rsr.setPassword("test");"> <return> <errorCode>0</errorCode> <messages>Successfully Authenticated User: // change to be the password of the account above rsr.setOrgId(1); rsr.setFunction("VALIDATEPASSWORD"); AdministrationPerson ap = new AdministrationPerson(); ap.setUserId("john.smith@yellowfin.com.au"); ap.setPassword("test"); rsr.setPerson(ap); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { out.write("Password is expired"); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); } %>

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).
admin@yellowfin.com.au</messages> <messages>Web Service Request Complete</messages> <sessionId>5fbbf0f2d8a6f4902adde5bfb659fed7</sessionId> <statusCode>SUCCESS</statusCode> </return> </ns2:remoteAdministrationCallResponse> </S:Body> </S:Envelope>

Instructions
See below for step-by-step instructions on how to perform this call, using a Java example:
Expand
title Step-by-step instructions
Start with a basic request for this function, which includes logging in as the admin user and specifying the web service call to perform
...
Expand
title CHANGEPASSWORD
This function will call the Yellowfin web service and change the password for the specified Yellowfin user. The password will be reset for a user specified through the AdministrationPerson parameter, based on their user ID (email address or another type of ID depending on the Login ID method).

This example shows a basic request for this call
:

Code Block
language java
AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.setPassword("test"); rsr.setOrgId(1); rsr.setFunction("
CHANGEPASSWORD
SETAVATARIMAGE");

Specify

You can specify the user
using the AdministrationPerson object
by providing their IP ID:
Code Block
language java
AdministrationPerson ap = new AdministrationPerson(); ap.setIpId(5); rsr.setPerson(ap
.setUserId("john.smith@yellowfin.com.au"); ap.setPassword("test123"); rsr.setPerson(ap
);

Select the image file, by using the java.nio.file library:
Code Block
language java
Path path = Paths.get("D:/TMP/fish.jpg"); // existing image file byte[] data = Files.readAllBytes(path); byte[] encodeBase64 = java.util.Base64.getEncoder().encode(data); String img = new String(encodeBase64, "UTF-8"); rsr.setParameters(new String[] {img});

Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize
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
the StatusCode parameter. See the Response Parameters table above for details.

Complete Example
Below is a complete full example of the CHANGEPASSWORD functionthis web service call. To use it for yourself, carry out the following the steps:
Copy the code and save it as ws_ changepwdsetavatarimage.jsp.
Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
Adjust the host, port, and admin user and user/new password details according to your environment.
Run http://<host>:<port>/ws_ changepwdsetavatarimage.jsp from your Internet browser.

Code Block
language java
theme Eclipse
<% /* ws_setavatarimage.jsp /* ws_changepwd.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.*" %> <%@ page import="java.nio.textfile.*Files" %> <%@ page import="comjava.hofnio.webfile.form.*Paths" %> <%@ page import="comjava.hofnio.mi.web.service.*file.Path" %> <% 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 web webservicesservices admin account rsr.setPassword("test"); // change to be the password of the above account above rsr.setOrgId(1); rsr.setFunction("CHANGEPASSWORDSETAVATARIMAGE"); AdministrationPerson ap = new AdministrationPerson(); ap.setIpId(5); rsr.setPerson(ap.setUserId("john.smith@yellowfin.com.au"); ap.setPassword("test123"); rsr.setPerson(ap); ); Path path = Paths.get("D:/TMP/fish.jpg"); // existing image file byte[] data = Files.readAllBytes(path); byte[] encodeBase64 = java.util.Base64.getEncoder().encode(data); String img = new String(encodeBase64, "UTF-8"); rsr.setParameters(new String[] {img}); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { out.write("Password is reset Success"); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); } %>

User Session Termination
These services can end user's Yellowfin sessions.
Anchor
resetpasswdlogoutuserresetpasswd
logoutuser
Expand
title RESETPASSWDLOGOUTUSER
This function resets a user's Yellowfin account and prompts them to change their password.
Note: This call will not change the password of the account itself. To change the password, use the CHANGEPASSWORD function.

Here is what a basic request for this call will look like
service terminates a Yellowfin session. However, it requires the LoginSessionId to be able to log the user out. This is is enough to identify the user, hence the user ID is not required. When a single sign-on is performed with either the LOGINUSER or LOGINUSERNOPASSWORD functions, you can get the LoginSessionId via:
Code Block
language java
AdministrationServiceRequest
String
rsr
token =
new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.setPassword("test"); rsr.setOrgId(1); rsr.setFunction("RESETPASSWD"); Use the AdministrationPerson object to identify the user whose account is to be reset:
Code Block
language java
AdministrationPerson ap = new AdministrationPerson(); ap.setUserId("john.smith@yellowfin.com.au"); rsr.setPerson(ap);
Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.
response.getLoginSessionId();

Save this value, so that you can pass it out to the LOGOUTUSER request later:
Code Block
language java
request.setLoginSessionId(token);

Request Elements
The following elements will be passed with this request:
Request Element
Data Type
Description
LoginId
String
Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method.
This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password
String
Password of the above account.
OrgId
Integer
Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function
String
Web services function. Set this to "LOGOUTUSER".
Person AdministrationPerson This object will contain the details of the use who is to be logged out. See the table below.
LoginSessionId String Session token of the Yellowfin instance that needs to be terminated. This is enough to identify the user.
Anchor
logoutap
logoutap
Mandatory parameters to set in the AdministrationPerson object for this function:
AdministrationPerson

This call's response will contain these parameters:
Response
Element
Data Type
Description
StatusCode
UserId
String
Status of the web service call. Possible values include:
SUCCESS
FAILURE
User ID to identify the user whose details are to be changed. This can be the user ID or the email address, depending on the Logon ID method.
Password String Password of the above account.

Request Example

The following SOAP XML example shows the request for this function using the above parameters:

Code Block

language	xml

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>

Complete Example

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

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

Code Block

language	java

<%            
/*<function>LOGOUTUSER</function>
            <person>        ws_ resetpwd.jsp   
               *<userId>admin@yellowfin.com.au</
%>
<%@ 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");userId>
               <password>test</password>
            </person>
            <loginSessionId>39fb11047affb98c9d081fb48bed0093</loginSessionId>
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

Reponse Elements

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

Reponse Example

Here is the resposnse of the above SOAP XML call:

Code Block

language	xml

 <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0<//errorCode>
 provide your Yellowfin webservices admin account
rsr.setPassword("test");      <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Web Service Request Complete</messages>
   // change to be the password of the account above
rsr.setOrgId(1);
rsr.setFunction("RESETPASSWD");

AdministrationPerson ap = new AdministrationPerson();

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

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

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

...

<sessionId>9cad6c76734e329c298e7b15c57a19db</sessionId>
            <statusCode>SUCCESS</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

Instructions

See below for step-by-step instructions on how to perform this call, using a Java example:

Expand

title	Step-by-step instructions

Here is a basic request for this call, which includes logging in as the admin user and specifying the web service call to perform

...

Expand

title	UPDATEUSER

This call will edit a user’s details. It accepts AdministrationPerson as a parameter, which can be used to identify the user, by providing their ID (for example, their email address, or another type of ID depending on the Login ID method).

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

Note: This call will not change the password of the user's account. To change the password, use the CHANGEPASSWORD function.

Here is what a basic request for this call will look like

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("

UPDATEUSER

LOGOUTUSER");

Then use the AdministrationPerson object to identify the user whose details are to be updated

Pass the login session ID:

Code Block
language java

AdministrationPerson ap = new AdministrationPerson(

rsr.setLoginSessionId(token);

ap.setUserId("john.smith@yellowfin.com.au");

If the user is logged into multiple Tomcat sessions simultaneously, then you can even specify which session to terminate by setting a parameter, for

Specify what detail is to be changed. For

example:

Code Block
language java

ap.setStutus("INACTIVE"); // This example shows that the user john.smith@yellowfin.com.au will not be able to log in rsr.setPerson(ap);

String[] _sessionId = new String[]{sessionId}; // log out by Tomcat session Id (cookies JSESSIONID) rsr.setParameters(_sessionId);
Only one session should be provided for termination per request. Note that the Tomcat session ID is optional; if omitted, Yellowfin will terminate all of the user's sessions.
Once the request is configured, perform the call:
Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

This call's response will

contain these 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

contain the StatusCode parameters. See the Response Parameters table for more details.

Complete Example

Below is a complete example of the LOGOUTUSER function. This script is designed to perform the following steps:

Call the LOGINUSER service which retrieves the LoginSessionId;
Configures the login link. You will need to click this link first, to initialize a Yellowfin session for the specifed user. (In our example we will log in the user john.smith@yellowfin.com.au. Make sure that the user you mention, already exists in your Yellowfin instance, or you can even modify the userId.)
Configure the link to log out. You will need to click this once the session has started.

To use this script UPDATEUSER function. To use it for yourself, carry out the following the steps:

Copy the code and save it as ws_updateuserlogoutuser.jsp.
Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
Adjust the host, port, admin user and user to update login/logout according to your environment.
Run http://<host>:<port>/ws_updateuserlogoutuser.jsp from your Internet browser.

Code Block

language	java

<%            
/*              logoutuser.jsp    ws_updateuser.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"); %>
<%@ page import="com.hof.mi.web.service.*" %>
<% 
AdministrationServiceService s_adm = new AdministrationServiceServiceLocator("localhost",8080,        "/services/AdministrationService", false);          // changeadjust tohost beand theport passwordnumber
AdministrationServiceSoapBindingStub ofadminService the account above
rsr.setOrgId(1);
rsr.setFunction("UPDATEUSER");


AdministrationPerson ap= (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService();
AdministrationServiceRequest rsr = new AdministrationPersonAdministrationServiceRequest();
ap.setUserId("john.smith@yellowfin.com.au");
ap.setStutus("INACTIVE");
rsr.setPerson(ap);

AdministrationServiceResponse rs
String token = adminServicerequest.remoteAdministrationCallgetParameter(rsr"token");

if ("SUCCESS".equals(rs.getStatusCode())  (token == null) {
	
	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() );
}
%>

User Session Termination

These services can end user's Yellowfin sessions.

...

Expand

title	LOGOUTUSER

This service terminates a Yellowfin session. However, it requires the LoginSessionId to be able to log the user out, which is enough to identify the user, hence the user ID is not required. When a single sign-on is performed with either the LOGINUSER or LOGINUSERNOPASSWORD functions, you can get the LoginSessionId via:

Code Block

language	java

String token = response.getLoginSessionId();

Save this value, so that you can pass it out to the LOGOUTUSER request later:

Code Block

language	java

request.setLoginSessionId(token);

Here is a basic request for this call:

Code Block

language	java

AdministrationServiceRequest rsr = new AdministrationServiceRequest();

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

rsr.setFunction("LOGOUTUSER");

Pass the login session ID:

Code Block

language	java

rsr.setLoginSessionId(token);

If the user is logged into multiple Tomcat sessions simultaneously, then you can even specify which session to terminate by setting a parameter, for example:

Code Block

language	java

String[] _sessionId = new String[]{sessionId}; // logout by Tomcat session Id (cookies JSESSIONID)
rsr.setParameters(_sessionId);

Only one session should be provided for termination per request. Note that the Tomcat session ID is optional; if omitted, Yellowfin will terminate all of the user's sessions.
Once the request is configured, perform the call:

Code Block

language	java

//login the admin user:

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

	AdministrationPerson ap = new AdministrationPerson();

	String userId = "john.smith@yellowfin.com.au";

	ap.setUserId(userId);
	ap.setPassword("test");

	rsr.setPerson(ap);

	AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);

	if ("SUCCESS".equals(rs.getStatusCode()) ) {
		String token_ = rs.getLoginSessionId();
		out.write("Login by opening the link in a new subtab prior to Logout. The tomcat session must be initialized...");
		out.write("<BR>Login: <A href='http://localhost:8080/logon.i4?LoginWebserviceId=" + token_ + "'>");
		out.write("http://localhost:8080/logon.i4?LoginWebserviceId=" + token_ + "</a><br>");
		out.write("<BR>Logout: <A href='http://localhost:8080/test.jsp?token=" + token_ + "&userId=" + userId + "'>");
		out.write("http://localhost:8080/test.jsp?token=" + token_ + "&userId=" + userId + "</a><br>");
	} else {
		out.write("Failure");
		out.write(" Code: " + rs.getErrorCode() );
		return;
	}
} else {

	//logout the user:

	out.write("Trying to logout " + token + " session...<br>");

	rsr = new AdministrationServiceRequest();

	rsr.setLoginId("admin@yellowfin.com.au");          // provide your Yellowfin web services admin account
	rsr.setPassword("test");                           // set the password of the above account
	rsr.setOrgId(1);

	rsr.setFunction("LOGOUTUSER");

	rsr.setLoginSessionId(token);

	AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr

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

Anchor
logoutbyuserid
logoutbyuserid
Expand
title LOGOUTBYUSERID
This service is similar to the LOGOUTUSER function in that it logs out a specified user, however this one requires either a user ID (for example, an email address or any other type of ID depending on the Login ID method) or a user's IP ID (that is, the value of the IpId field in the Person table in Yellowfin's database), rather than a login session ID to identify the user.
This call uses the AdministrationPerson object which is used to provide the user ID or IpId.

Request Elements
The following elements will be passed with this request:
Request Element
Data Type
Description
LoginId
String
Yellowfin web services admin user Id. This can be the user ID or the email address, depending on the Logon ID method.
This Yellowfin account must have the “web services” role enabled, and must belong to the Default (i.e. Primary) Org.
Password
String
Password of the above account.
OrgId
Integer
Default (i.e. Primary) organization ID within Yellowfin. Always set this to 1.
Function
String
Web services function. Set this to "LOGOUTBYUSERID".
Person
AdministrationPerson
Object containing details of the user to log out. See table below.

Anchor
logoutuserap
logoutuserap
Set either one of these parameters in the AdministrationPerson object:
AdministrationPerson Element
Data Type
Description
UserId
String
User ID to identify the user to terminate their Yellowfin session. This can be the user ID or the email address, depending on the Logon ID method.
IpId String Ip ID of the user whose session is to be terminated.

Request Example
The following XML SOAP example shows a request for this function being passed:
Code Block
language xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/"> <soapenv:Header/> <soapenv:Body> <web:remoteAdministrationCall> <arg0> <loginId>admin@yellowfin.com.au</loginId>
Initialize the Administration web service. Click here to learn how to do this.

This call's 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 LOGOUTUSER function. This script is designed to perform the following steps:
Call the LOGINUSER service which retrieves the LoginSessionId;
Configures the login link. You will need to click this link first, to initialize a Yellowfin session for the specifed user. (In our example we will log in the user john.smith@yellowfin.com.au. Make sure that the user you mention, already exists in your Yellowfin instance, or you can even modify the userId.)
Configure the link to log out. You will need to click this once the session has started.

To use this script for yourself, carry out the following the steps:
Copy the code and save it as test.jsp.
Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
Adjust the host, port, admin user and user to login/logout according to your environment.
Run http://<host>:<port>/test.jsp from your Internet browser.

Code Block
language java
<% /* test.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(); String token = request.getParameter("token"); if (token == null) { //login the user: rsr.setLoginId("admin@yellowfin.com.au"); // provide your Yellowfin webservices admin account rsr.setPassword("test"); <password>test</password> <orgId>1</orgId> // change to be the password of the account above rsr.setOrgId(1); rsr.setFunction("LOGINUSER"); AdministrationPerson ap = new AdministrationPerson(); String userId = "john.smith@yellowfin.com.au"; ap.setUserId(userId); ap.setPassword("test"); rsr.setPerson(ap); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { String token_ = rs.getLoginSessionId(); out.write("Login by opening the link in a new subtab prior to Logout. The tomcat session must be initialized..."); out.write(" Login: <A href='http://localhost:8080/logon.i4?LoginWebserviceId=" + token_ + "'>"); out.write("http://localhost:8080/logon.i4?LoginWebserviceId=" + token_ + "</a> "); out.write(" Logout: <A href='http://localhost:8080/test.jsp?token=" + token_ + "&userId=" + userId + "'>"); out.write("http://localhost:8080/test.jsp?token=" + token_ + "&userId=" + userId + "</a> "); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); return; } } else { //logout the user: out.write("Trying to logout " + token + " session... "); rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au");<function>LOGOUTBYUSERID</function> <person> <userId>admin@yellowfin.com.au</userId> <password>test</password> </person> </arg0> </web:remoteAdministrationCall> </soapenv:Body> </soapenv:Envelope>

Reponse Elements
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

Request Example
The response of our above SOAP example is shown below:
Code Block
language xml
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/"> <return> // provide your Yellowfin webservices admin account rsr.setPassword("test");<errorCode>0</errorCode> <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages> <messages>Web Service Request Complete</messages> <sessionId>f8a04d7c9530ff18f65f95048e6a4500<//sessionId> change to be the password of the account above rsr.setOrgId(1); rsr.setFunction("LOGOUTUSER"); rsr.setLoginSessionId(token); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { out.write("Logout: Success"); } else { out.write("Failure"); out.write("Code: " + rs.getErrorCode() ); } } %>

...
<statusCode>SUCCESS</statusCode> </return> </ns2:remoteAdministrationCallResponse> </S:Body> </S:Envelope>

Instructions
See below for step-by-step instructions on how to perform this call, using a Java example:
Expand
title Step-by-step instructions
...
Expand
title LOGOUTBYUSERID

This service is similar to the LOGOUTUSER function in that it logs out a specified user, however this one requires either a user ID (for example, an email address or any other type of ID depending on the Login ID method) or a user IpID (that is, the value of the IpId field in the Person table in Yellowfin's database), rather than a login session ID to identify the user.
This call uses the AdministrationPerson object which is used to provide the user ID or the user IpId.

Here is a basic request for this call, which includes logging in as the admin user and specifying the web service call to perform:

Code Block
language java
AdministrationServiceRequest rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); rsr.setPassword("test"); rsr.setOrgId(1); rsr.setFunction("LOGOUTBYUSERID");

Identify the user to log out, by passing their user ID or IpId:

Code Block
language java
AdministrationPerson ap = new AdministrationPerson(); ap.setUserId(userId); rsr.setPerson(ap);

If the user is logged into multiple Tomcat sessions simultaneously, then you can specify which session to terminate by setting a parameter, for example:

Code Block
language java
String[] _sessionId = new String[]{sessionId}; // log
logout
out by Tomcat session Id (cookies JSESSIONID) rsr.setParameters(_sessionId);
Only one session should be provided for termination per request. Note that the Tomcat session ID is optional; if omitted, Yellowfin will terminate all of the user's sessions.

Once the request is configured, perform the call:

Code Block
language java
AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);
Initialize the Administration web service. Click here to learn how to do this.

This call's response will contain
these parameters:
Response Element
Data Type
Description
StatusCode
String
Status of the web service call. Possible values include:
SUCCESS
FAILURE

the StatusCode parameters. See the Response Parameters table above for more details.

Complete Example
Below is a complete example of the LOGOUTUSER this function. This script is designed to perform the following steps:
Configures the login link. You will need to click this link first, to initialize a Yellowfin session for the specifed user. (In our example we will log in the user john.smith@yellowfin.com.au. Make sure that the user you mention, already exists in your Yellowfin instance, or you can even modify the userId.)
Configure the link to log out. You will need to click this once the session is set up.

To use this script for yourself, carry out the following the steps:
Copy the code and save it as test.jsp.
Put the file in the root folder: Yellowfin/appserver/webapps/ROOT.
Adjust the host, port, admin user and user to login/logout according to your environment.
Run http://<host>:<port>/test.jsp from your Internet browser.

Code Block
language java
<% /* test.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(); String userId = request.getParameter("userId"); if (userId == null) { //login the admin user: rsr.setLoginId("admin@yellowfin.com.au"); // provide your Yellowfin webservicesweb services admin account rsr.setPassword("test"); // change to beset the password of the above account above rsr.setOrgId(1); rsr.setFunction("LOGINUSER"); AdministrationPerson ap = new AdministrationPerson(); userId = "john.smith@yellowfin.com.au"; ap.setUserId(userId); ap.setPassword("test"); rsr.setPerson(ap); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { String token_ = rs.getLoginSessionId(); out.write("Login by opening the link in a new subtab prior to Logout. The tomcat session must be initialized..."); out.write(" Login: <A href='http://localhost:8080/logon.i4?LoginWebserviceId=" + token_ + "'>"); out.write("http://localhost:8080/logon.i4?LoginWebserviceId=" + token_ + "</a> "); out.write(" Logout: <A href='http://localhost:8080/test.jsp?token=" + token_ + "&userId=" + userId + "'>"); out.write("http://localhost:8080/test.jsp?token=" + token_ + "&userId=" + userId + "</a> "); }else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); return; } } else { //logout the user: out.write("Trying to logout " + userId + " session... "); rsr = new AdministrationServiceRequest(); rsr.setLoginId("admin@yellowfin.com.au"); // provide your Yellowfin webservicesweb services admin account rsr.setPassword("test"); // change to be the password of the above account above rsr.setOrgId(1); rsr.setFunction("LOGOUTBYUSERID"); AdministrationPerson ap = new AdministrationPerson(); ap.setUserId(userId); rsr.setPerson(ap); AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr); if ("SUCCESS".equals(rs.getStatusCode()) ) { out.write("Logout: Success"); } else { out.write("Failure"); out.write(" Code: " + rs.getErrorCode() ); } } %>

User ID to identify the user whose details are to be changed. This can be the user ID or the email address, depending on the Logon ID method.
Password	String	Password of the above account.

Content

Space Tools

Page History

Versions Compared

Old Version 20

New Version Current

Key

Main User Management Functions

Request Parameters

Request Example

Complete Example

Reponse Parameters

Reponse Example

Instructions

Complete Example

Complete Example

Request Parameters

Reponse Parameters

Instructions

Complete Example

Request Parameters

Reponse Parameters

Instructions

Request Elements

Request Example

Reponse Elements

Response Example

Instructions

Complete Example

Retrieving & Validating User Information

Request Elements

Request Example

Reponse Elements

Reponse Example

Instructions

Request Elements

Request Example

Response Elements

Response Example

Instructions

Request Elements

Request Example

Reponse Elements

Reponse Example

Instructions

Complete Example

Request Parameters

Request Example

Response Parameters

Response Example

Instructions

Complete Example

Request Elements

Request Example

Reponse Elements

Reponse Example

Instructions

Complete Example

Request Elements

Request Example

Reponse Elements

Reponse Example

Instructions

Complete Example

Manipulating User Information

Request Elements

Request Example

Reponse Elements

Reponse Example

Instructions

Request Elements

Request Example

Reponse Elements

Request Example

Instructions

Complete Example

Request Elements

Request Example

Reponse Elements

Complete Example