Page History

Versions Compared

Key

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

...

Table of Contents

class	contents

...

シングルサインオン

Styleclass

Class	topLink

Administration Service ページトップ

Expand

title	LOGINUSER (Single Sign On)	LOGINUSER（シングルサインオン）

このサービスは、Yellowfinに接続し、指定されたユーザーのログオントークンを取得します。このトークンがYellowfinログオンURLに渡されると、認証されるユーザーのログイン画面が無効化され、そのユーザーのセッションがただちに開始されます。This service connects to Yellowfin and retrieves a logon token for a given user. When this token is passed to the Yellowfin Logon URL it will disable the login screen for the authenticated users and their session will being immediately.

Code Block

AdministrationServiceResponse rs = null;
AdministrationServiceRequest rsr = new AdministrationServiceRequest();
   
rsr.setLoginId("admin@yellowfin.com.au");
rsr.setPassword("test");
rsr.setOrgId(new Integer(1));
rsr.setFunction("LOGINUSER");
     
AdministrationPerson ap = new AdministrationPerson();
ap.setUserId("admin@yellowfin.com.au");
ap.setPassword("test");
rsr.setPerson(ap);
     
rs = rssbs.remoteAdministrationCall(rsr);
    
if ("SUCCESS".equals(rs.getStatusCode()) ) {
				
	out.write("Success");
	out.write("URL:  http://<yellowfin-server>/logon.i4?LoginWebserviceId=" + rs.getLoginSessionId()); 
                			
} else {
			
	out.write("Failure");
				
}

The LOGINUSER function will Single Sign On a given user into Yellowfin. The contents of the AdministrationPerson object will be used to define the user being logged in.LOGINUSER関数は、指定されたユーザーをYellowfinにシングルサインオンさせます。AdministrationPersonオブジェクトの内容は、ログインしているユーザーを定義するために使用されます。

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

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 login. This can be the user ID or the email address, depending on the Logon ID method.
Password	String	Password of the new user.

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

LoginSessionId

String

A unique login token. This token is appended to the Login URL to take a user directly into Yellowfin.

Redirecting to Yellowfin with the login token

Using the token received from the webservice call (the contents of AdministrationResponse.LoginSessionId), you can forward the user to the URL:

http://<YELLOWFIN-SERVER>/logon.i4?LoginWebserviceId=<TOKEN>

This URL will bypass the authentication screen in Yellowfin and take the user directly into Yellowfin.

The token has a limited validity period. It must be used within 5 minutes, and once it has been used, it cannot be used again. To make subsequent calls from a third party application into Yellowfin, you must call the LOGINUSER web service again.

Using the token with the JavaScript API

The SSO token can also be used with embedded JavaScript API widgets. The token is added to the scriptlet URL like this:

<script type="text/javascript" src="http://localhost/JsAPI?dashUUID=e9a6ab0a-bcb0-4fe6-9663-4dd33e58f08e&token=<TOKEN>"></script>

Specifying Session Options

You can pass variables/switches that toggle functionality only for the session created via this Single Sign On request. These options can be enabled by passing them via the Parameters attribute in the AdministrationRequest, or by appending them to the redirection URL.

Parameters are added to the AdministrationRequest.Parameters attribute as a list of key value pairs, like:

YFTOOLBAR=TRUE

ENTRY=DASHBOARD

Options passed on the login URL look like:

http://<yellowfin-server>/logon.i4?LoginWebserviceId=<token>&yftoolbar=true&entry=DASHBOARD

Here is a list of the available options:

Parameter Option Key	URL Option Key	Description
YFTOOLBAR	yftoolbar	`TRUE`/`FALSE`. Hide the Yellowfin toolbar for this session.
ENTRY	entry	Determine the user's only entry point on completion of the login process. This is used in conjunction with other parameters to determine the content the user is shown. Possible values: `DASHBOARD` `REPORTLIST` `BROWSE` `BROWSETAB` `CREATEREPORT` `EDITREPORT` `VIEWREPORT` `ADMINISTRATION` `EDITDASHBOARD` `VIEWDASHBOARD` `VIEWSTORYBOARD` `TIMELINE`
REPORTID	reportid	Used with `ENTRY = EDITREPORT` or `VIEWREPORT`. This is the internal Id of the report to redirect to.
REPORTUUID	reportuuid	Used with `ENTRY = EDITREPORT` or `VIEWREPORT`. This is the UUID of the rpeort to redirect to.
STORYBOARDUUID	storyboarduuid	Used with `ENTRY = VIEWSTORYBOARD`. This is the UUID of the storyboard to redirect to.
MOBILEDEVICE	mobiledevice	`TRUE`/`FALSE`. Takes the user to a mobile version of the Yellowfin interface.
REPORTNAME	reportname	Used with `ENTRY = EDITREPORT` or `VIEWREPORT`. This is the name of the report to redirect to.
DISABLESOURCEFILTERS		`TRUE`/`FALSE`. Disable Source Filter or Client Reference Filters for this user, for this session. This allows the user to see all data. This doesn't work for content based on Client Source Substitution.
DISABLEHEADER	disableheader	`TRUE`/`FALSE`. Hide the Yellowfin header for this session.
HIDEHEADER	hideheader	Same as `DISABLEHEADER`.
DISABLEFOOTER	disablefooter	`TRUE`/`FALSE`. Hide the Yellowfin footer for this session.
HIDEFOOTER	hidefooter	Same as `DISABLEFOOTER`.
DISABLESIDENAV	disablesidenav	`TRUE`/`FALSE`. Hide the Yellowfin side navigation for this session.
HIDESIDENAV	hidesidenav	Same as `DISABLESIDENAV`.
DISABLELOGOFF	disablelogoff	`TRUE`/`FALSE`. Hide the Yellowfin logoff link for this session.
HIDELOGOFF	hidelogoff	Same as `DISABLELOGOFF`.
REASONCODE	reasoncode	Custom string (80 ASCII characters) that will be dropped into all events generated by this session. Events are dropped in the Event table in the Yellowfin database. This option can also be used with the JavaScript API.
REASONDESCRIPTION	reasondescription	Custom string (2048 ASCII characters) that will be dropped into all events generated by this session. Events are dropped in the Event table in the Yellowfin database. This option can also be used with the JavaScript API.
DASHBOARDID	dashboardid	Used with `ENTRY = EDITDASHBOARD` or `VIEWDASHBOARD`. This is the internal id of the dashboard tab to redirect to.
DASHBOARDUUID	dashboarduuid	Used with `ENTRY = EDITDASHBOARD` or `VIEWDASHBOARD`. This is the internal id of the dashboard tab to redirect to.
FILTER<ID>	filter<ID>	Used with `ENTRY = VIEWREPORT`. Override filter values for the given report. FILTER is appended with the internal ID of the filter, plus the string representation of the filter value. For example: `FILTER2134=MALE` You can pass multiple filters for the one report.
SOURCEFILTER_<FILTERCODE>		Override the source filter values for this user for this session. `SOURCEFILTER_` is appended with the Filter Type Code from the Source Filter setup page, plus the value you wish to give access to. For example: `SOURCEFILTER_COUNTRY=AU` You can pass multiple source filter values for the one session. This option can also be used with the JavaScript API.
CONTENT_<INCLUDE/EXCLUDE>		Override the content access that a user has for this session. `CONTENT_` is appended with either `INCLUDE` or `EXCLUDE`. The value for this key is either the Content Category Code, or the Content Category UUID. If you choose to `INCLUDE` content, then these will be the only Content Categories that the user will have access to. If you choose to `EXCLUDE` content, then these excluded Content Categories will be removed from the content that the user normally has access to. Inclusion and Exclusion of content is based on the Category level. All sub categories with the specified category are included or excluded. An example of including/excluding with category codes and UUIDs: `CONTENT_INCLUDE=TUTORIAL` `CONTENT_INCLUDE=c83357db-8aef-4ec7-ab72-fce34de9ee77` `CONTENT_EXCLUDE=TUTORIAL` `CONTENT_EXCLUDE=c83357db-8aef-4ec7-ab72-fce34de9ee77` It is not logical to use both `INCLUDE` and `EXCLUDE` for the same session. This option can also be used with the JavaScript API.

Expand

title	LOGINUSERNOPASSWORD (Single Sign On)

This service is a drop in replacement for LOGINUSER, but the password for the user being logged in is not required.

Options are the same as LOGINUSER except for:

AdministrationRequest.Function will be set to LOGINUSERNOPASSWORD
AdministrationPerson.Password can be blank

An extra parameter needs to be added to the Configuration table of the Yellowfin database to enable this functionality:

IpOrg	ConfigTypeCode	ConfigCode	ConfigData
1	SYSTEM	SIMPLE_AUTHENTICATION	TRUE

You may need to restart Yellowfin for the database change to take affect.

You will receive a web service arror 26: UNSECURE_LOGIN_NOT_ENABLED if this configuration option is not added to the Yellowfin database.

User Replication and Managment

Styleclass

Class	topLink

Administration Service top

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

...

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

Functions

Expand

title	ADDUSER

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

Code Block

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

person.setUserId("test@yellowfin.com.au");
person.setPassword("test");
person.setFirstName("Simple");
person.setLastName("Simon");
person.setInitial("S");
person.setSalutationCode("MR");
person.setRoleCode("YFADMIN");
person.setEmailAddress("test@yellowfin.com.au");

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

rs = AdministrationService.remoteAdministrationCall(rsr);

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

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

This function will create a user in Yellowfin. The details in the AdministrationPerson object will be used in the user creation process.

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

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

AdministrationPerson Element	Data Type	Description
UserId	String	User ID of the 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
FirstName	String	First name of of the new user
LastName	String	Last name of of the new user
Initial	String	Middle name of the new user
SalutationCode	String	Title of the new user. Possible values include: DR MISS MR MRS MS
RoleCode	String	Yellowfin role. The specified role here can be the Org Reference Code (YFADMIN) or the name of the role (Yellowfin Administrator)
EmailAddress	String	Email address of the new user

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Expand

title	DELUSER / DELETEUSER

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

Code Block

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

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

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

rs = AdministrationService.remoteAdministrationCall(rsr);

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

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

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

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

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

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

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Retrieving & Validating User Information

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

...

Expand

title	VALIDATEPASSWORD

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

Code Block

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

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

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

rs = AdministrationService.remoteAdministrationCall(rsr);

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

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

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

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

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

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Manipulating User Information

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

...

Expand

title	CHANGEPASSWORD

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

Code Block

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

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

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

rs = AdministrationService.remoteAdministrationCall(rsr);

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

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

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

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

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

The response returned will contain these parameters:

Response Element

Data Type

Description

StatusCode

String

Status of the web service call. Possible values include:

SUCCESS
FAILURE

Retrieving Objects Belonging to a User

Styleclass

Class	topLink

Administration Service top

Objects belonging to a user in a Primary or Client Organisation can be retrieved with various web service calls. The objects returned in the response will be dependent on the type of call made in the request.

...

Expand

title	LOADTABREPORTS

This function will return a list of reports contained within a specified dashboard tab, that is accessible by a specified user in Yellowfin.

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

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

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

AdministrationReportGroup Element	Data Type	Description
ReportGroupId	String	Dashboard Tab ID

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

ReportGroups

AdministrationReportGroup

An array of AdministrationReportGroup objects. These objects hold dashboard metadata. For this particular function, the reports’ metadata is also loaded into this object’s GroupReports() parameter.

Group & Role Administration

Styleclass

Class	topLink

Administration Service top

Groups and Roles can be created and modified with a web service call. The objects returned in the response is dependent on the type of call made in the request.

...

Expand

title	DELETEGROUP

The following code will call the Yellowfin web service and delete the specified group in Yellowfin:

Code Block

AdministrationServiceRequest rsr = new AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationGroup group = new AdministrationGroup();

group.setGroupName("Group Name");

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(new Integer(1));
// uncomment line below and set Client Reference ID if you wish to get the group in a client organisation
// rsr.setOrgRef("CLIENTREFERENCEIDHERE");
rsr.setFunction("DELETEGROUP");
rsr.setGroup(group);

rs = AdministrationService.remoteAdministrationCall(rsr);

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

This function will delete a specified group from Yellowfin.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices eg. admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary organisation ID within Yellowfin. Always set this to 1.
Function = “DELETEGROUP”	String	Web services function
OrgRef	String	Client Reference ID if this function is to be applied for a particular client organisation. The parameter is optional.
Group	AdministrationGroup	The AdministrationGroup object holding the Yellowfin user group’s name for the retrieval process

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

AdministrationGroup Element	Data Type	Description
GroupName	String	Name of the specified Yellowfin group

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

Client Organisation Functionality

Styleclass

Class	topLink

Administration Service top

Yellowfin contains functionality called Client Organisations, which allows multiple virtual instances of Yellowfin to reside in the same server instance.

...

Expand

title	IMPORTCONTENT

The following code will call the Yellowfin web service and import the specified Yellowfin import objects into the application:

Code Block

AdministrationServiceRequest rsr = new AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
Byte[] data = <XML import file>;

rsr.setLoginId(this.username);
rsr.setPassword(this.password);
// This is the primary organisation
rsr.setOrgId(new Integer(1));
rsr.setFunction("IMPORTCONTENT");
rsr.setParameters( new String[] { Base64.encodeBytes(data) } );

rs = AdministrationService.remoteAdministrationCall(rsr);

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

Refer to ws_admin_import.jsp in your Yellowfin web services directory Yellowfin\development\examples\web services for a more detailed example of how this function would work.

Request Element	Data Type	Description
LoginId	String	Login ID of the account used to connect to Yellowfin webservices i.e admin@yellowfin.com.au
Password	String	Password of the account used to connect to Yellowfin webservices
OrgId	Integer	Primary Organisation ID within Yellowfin. Always set this to 1
Function = “IMPORTCONTENT”	String	Web services function
Parameters	Array (String)	An array of Base64 encoded chunks of the XML import file
ImportOptions	Array(ImportOption)	An array of ImportOption objects that controls how content is imported.

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

Object Definitions

Styleclass

Class	topLink

Administration Service top

Expand

title	AdministrationPerson

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

...

horizontalrule

Styleclass

Class	topLink

Administration Service top

Content

Space Tools

Versions Compared

Old Version 6

New Version 7

Key

シングルサインオン

Redirecting to Yellowfin with the login token

Using the token with the JavaScript API

Specifying Session Options

User Replication and Managment

Functions

Retrieving & Validating User Information

Manipulating User Information

Retrieving Objects Belonging to a User

Group & Role Administration

Client Organisation Functionality

Object Definitions