Table of Contents
Integration Guide
Users, Security, Web Services & Client Organisation
Functionality
Release 5.0
June 2010
Yellowfin ®
Release 5.0
Integration Guide
Under international copyright laws, neither the documentation nor the software may be copied, photocopied,
reproduced, translated or reduced to any electronic medium or machine-readable form, in whole or in part, without
the prior written permission of Yellowfin International Pty Ltd, except in the manner described in the software
agreement.
The information in this document is subject to change without notice. If you find any problems with this
documentation, please report them to Yellowfin in writing at [email protected] Yellowfin does not warrant
that this document is error free.
Copyright © Yellowfin International 2010. All rights reserved.
Portions © Copyright Microsoft Corporation. All rights reserved.
Trademarks:
Yellowfin and the Yellowfin Logo are registered trademarks of Yellowfin International.
All other product and company names mentioned herein are the trademarks of their respective owners.
Version: 1
Published: June 2010
3
Table of Contents
Table of Contents ....................................................................................................................................................... 3
Chapter 1 - Introduction ............................................................................................................................................. 6
Overview ............................................................................................................................................................... 6
Integration Project Planning .................................................................................................................................. 6
Web Services ......................................................................................................................................................... 8
Yellowfin Web Services API ................................................................................................................................... 8
Chapter 2 - User Replication .................................................................................................................................... 10
Overview ............................................................................................................................................................. 10
Creating Users ..................................................................................................................................................... 10
Manipulating Users .............................................................................................................................................. 11
Retrieving User Information ................................................................................................................................ 13
Deleting a User.................................................................................................................................................... 14
Changing a Users Password................................................................................................................................. 15
Chapter 3 - Single Sign On ....................................................................................................................................... 16
Overview ............................................................................................................................................................. 16
Performing Single Sign On .................................................................................................................................. 16
Performing Single Sign On without a Password.................................................................................................. 17
Web Service Logon Parameters ........................................................................................................................... 19
Performing a Logoff via Web services................................................................................................................. 21
Chapter 4 - Defining Functional Access .................................................................................................................... 23
Overview ............................................................................................................................................................. 23
Changing a Users Role via the Yellowfin Interface ............................................................................................. 23
Changing a Users Role via Web Services............................................................................................................. 24
Chapter 5 - Row Level Security ................................................................................................................................ 25
Overview ............................................................................................................................................................. 25
Prerequisites........................................................................................................................................................ 25
Assigning a Relationship between a User and Data Values ................................................................................ 25
Validating that the SQL Query is Correct ............................................................................................................. 28
Scheduling Source Filters to Update Automatically ............................................................................................. 28
Assigning a Source Filter to a View Field ............................................................................................................ 29
Chapter 6 - Report Level Security ............................................................................................................................ 30
Overview ............................................................................................................................................................. 30
Access Level Security on Report Subcategories .................................................................................................. 30
Assigning Users to Groups via the Yellowfin Interface ....................................................................................... 31
Assigning Users to Groups via the Yellowfin Web service .................................................................................. 32
Retrieving Group Members via the Yellowfin Web service ................................................................................. 34
Chapter 7 - Client Organisation Functionality........................................................................................................... 35
Overview ............................................................................................................................................................. 35
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
4
Creating a Client Organisation ............................................................................................................................. 36
Deleting a Client Organisation............................................................................................................................. 36
Modifying a Client Organisation .......................................................................................................................... 37
Listing all Client Organisations ............................................................................................................................ 38
Retrieving a Client Organisation.......................................................................................................................... 39
List Users Who Have Access to a Client Organisation.......................................................................................... 39
List Client Organisations accessible by a User ..................................................................................................... 40
Grant User Access to a Client Organistion ........................................................................................................... 41
Remove User Access to a Client Organistion ....................................................................................................... 42
Chapter 8 - Application & UI Integration .................................................................................................................. 44
Overview ............................................................................................................................................................. 44
Frames based integration.................................................................................................................................... 44
Custom Header & Navigation .............................................................................................................................. 45
Embeddable Java Client ....................................................................................................................................... 46
Web Services Integration .................................................................................................................................... 47
Inline System Integration .................................................................................................................................... 48
Navigation Replacement & Functionality ....................................................................................................... 49
Customising Navigation Areas ........................................................................................................................ 49
Customised Toolbar ............................................................................................................................................. 51
Chapter 9 - Silent Installer ....................................................................................................................................... 52
Overview ............................................................................................................................................................. 52
Download the silent installer jar ......................................................................................................................... 52
Silent Installer Properties File ............................................................................................................................. 53
Error Messages .................................................................................................................................................... 55
Deploying inside the Yellowfin tomcat container. .............................................................................................. 56
Chapter 10 - LDAP .................................................................................................................................................... 57
Overview ............................................................................................................................................................. 57
Preparing LDAP Integration ................................................................................................................................. 57
Defining the Default Role.................................................................................................................................... 58
Users Provisioning and Sign-on ........................................................................................................................... 59
Example .......................................................................................................................................................... 60
Using LDAP Groups for Yellowfin Security ........................................................................................................... 62
Chapter 11 - Out of the Box Content ....................................................................................................................... 63
Overview ............................................................................................................................................................. 63
Command Line Data Source Creation .................................................................................................................. 63
datasource.properties.txt ................................................................................................................................ 64
Command Line Report definition XML importer .................................................................................................. 67
import.properties.txt....................................................................................................................................... 67
Setting up report categories................................................................................................................................ 68
Report Migration ................................................................................................................................................. 68
Appendix A – Web Services Further Information ...................................................................................................... 69
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
5
Yellowfin Java Web Services API .................................................................................................................... 69
SOAP ............................................................................................................................................................... 70
LISTCLIENTS...................................................................................................................................................... 71
GETCLIENT ........................................................................................................................................................ 71
CREATECLIENT .................................................................................................................................................. 72
DELETECLIENT ................................................................................................................................................... 72
UPDATECLIENT ................................................................................................................................................. 73
LISTUSERSATCLIENT .......................................................................................................................................... 73
GETUSERACCESS ............................................................................................................................................... 73
ADDUSERACCESS .............................................................................................................................................. 74
REMOVEUSERACCESS ........................................................................................................................................ 74
LOGINUSER ...................................................................................................................................................... 75
GETUSERREPORTS............................................................................................................................................. 75
LISTGROUPS ..................................................................................................................................................... 75
GETGROUP ....................................................................................................................................................... 75
CREATEGROUP ................................................................................................................................................. 75
DELETEGROUP .................................................................................................................................................. 75
MODIFYGROUP ................................................................................................................................................ 75
LOADBIRTREPORT............................................................................................................................................. 75
SCHEMA ........................................................................................................................................................... 75
Client Access Filter .......................................................................................................................................... 75
Appendix B – Client Orgs Further Information.......................................................................................................... 76
Data Sources ................................................................................................................................................... 76
Source Access Filters....................................................................................................................................... 76
Views .............................................................................................................................................................. 76
Report Categories ........................................................................................................................................... 76
Reports ........................................................................................................................................................... 77
Dashboards ..................................................................................................................................................... 77
Groups ............................................................................................................................................................ 77
Roles ............................................................................................................................................................... 77
User Management .......................................................................................................................................... 77
Person Search ................................................................................................................................................. 78
Web Services .................................................................................................................................................. 78
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
6
Chapter 1 - Introduction
Overview
Yellowfin allows partners and clients to integrate Yellowfin into an existing application
or intranet. This allows for seamless user and data integration, and for the replication
of user security at the report data level.
Integration usually involves the following steps:
• User Replication
• Single Sign On
• Defining Functional Access
• Row Level Security
• Report Level Security
• Client Organisation Implementation
• Application & User Interface Integration
This document will outline each of these steps in detail, as well as the use of:
• Silent Installer
• LDAP
• Out Of The Box Content
Integration Project Planning
Yellowfin provides a number of options for integrating with other applications – the
best selection of options will depend upon specific needs and the level of integration
required. Yellowfin recommends a project based approach to integrating Yellowfin
into an application – starting with an initial workshop / brain storming session to
understand what the desired level of integration is.
A typical project may include the following activities:
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
7
Phase
Est.
Time
Activities & Outcomes
How do I want to
integrate Yellowfin
1 Day
1-2 hour workshop to discuss the best approach
and desired outcome. Documentation of the
Implementation Plan.
Look & Feel
½ Day
Development of Yellowfin Style Sheet and
additional look and feel options.
Navigation
Integration
½ Day
Integration of Yellowfin into an application’s
navigation structures.
Removing
Yellowfin Logos &
References
2 Hours
Removing the powered by logo and Yellowfin
support links from the application
Security
Integration / Single
Sign On
1-5 Days
Development and testing of security integration.
Custom Roles and User Groups.
Security Filters
1-2 Days
Accessing the internal security framework for items
such as who can see what data.
Redefining Roles
& Functional
Access
1 Day
Matching roles and functional access within
Yellowfin to the existing functional security.
Setting up report
Categories &
Folders
½ Day
Creating report categories that help manage content
versus content created by customers.
Creating Views
2+ Days
Creating initial views of the application.
Marketing & Sales
Demo –
Development &
Training
1 Day
Development of pre-sales demonstration with some
initial content.
OOTB Report
Content
5+ Days
Development of initially deployed content.
Auto Dashboard
Tab Generation
½ Day
Enabling auto-polish of dashboard tabs to new
users as they are created within Yellowfin.
Silent Installer
2+ Days
Development of a silent installer to remove
Yellowfin logos etc and potentially integrate into the
application’s installer.
Technical &
Support Training
2 Days
Training by either Yellowfin technical staff or self
guided, for support and maintenance of Yellowfin.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
8
Web Services
Web Services are used for managing communication between the OEM application
and Yellowfin. The Web Services are XML based and independent of the
programming language used to develop the OEM application.
When developing against the Yellowfin Web Services, it is possible to generate
functional stubs against our WSDL definitions. The WSDL definitions of the Yellowfin
Web Services can be found at http://<yellowfin-server>:<port>/services. eg.
http://localhost:8080/services
The functional stubs will allow developers to make standard function calls in their
native programming language, which will directly communicate with the services
provided by Yellowfin. The process of creating functional stubs should also generate
any objects required by the web service.
Some of the objects used by the examples in this document include:
•
AdministrationRequest, An object that defines the type of call being made to the
web service.
•
AdministrationResponse, The object returned by the web service.
•
AdministrationPerson, An object that contains basic user information.
•
AdministrationGroup, An object that contains basic group information.
Calls to the Web Service will involve populating a request object, with any required
child objects populated.
Yellowfin Web Services API
Yellowfin ships with a JAR file called yfws.jar. This is located in the development
directory within the Yellowfin installation directory. The Yellowfin Web Service API
has pre-generated functional stubs for the Yellowfin Web Services. This can be used
directly in applications that are developed in Java, or other languages that support
Java integration, such as Cold Fusion and Lotus Script. This makes integration
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
9
slightly simpler as it doesn't require each request to be manually generated, as most
of the Web Services are wrapped by a standard Java function.
Requests are of the form:
asm= new AdministrationServiceClient(host, port, user,
password, service);
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
person.setFirstName("Simple");
person.setLastName("Simon");
person.setInitial("F");
person.setSalutationCode("DR");
person.setRoleCode("YFADMIN");
person.setEmailAddress("[email protected]");
boolean success = asm.editUser(person);
System.out.println("Edit User Success: " + success);
System.out.println("ErrorCode: " + asm.getErrorCode());
The yfws.jar file contains Java Documentation that outlines the functions that are
available.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
10
Chapter 2 - User Replication
Overview
User replication involves synchronising each user in the OEM application with a
named user in Yellowfin. This allows Yellowfin to identify the user who is logged in,
and to apply any restrictions that may be required. Sychronisation is usually
performed using web service calls from the OEM application to Yellowfin. This can
also be managed manually if users in the OEM application are generally static.
This chapter 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
an user modification is made in the OEM application.
Creating Users
When a new user is created in the OEM application, a call should be made to
Yellowfin to also create the user. An AdministrationPerson object should be
populated, attached to the AdministationRequest, and sent to Yellowfin.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
11
The following code will call the Yellowfin web service to create a user.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
person.setFirstName("Simple");
person.setLastName("Simon");
person.setInitial("F");
person.setSalutationCode("DR");
person.setRoleCode("YFADMIN");
person.setEmailAddress("[email protected]");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("ADDUSER");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
Manipulating Users
Once a user has been created, their details can be modified using another web
service call. Populate the person object with changes. The User Id field is used to
identify the user, so this cannot be changed. Also, the user’s password cannot be
changed using this web service, there is a CHANGEPASSWORD function for this.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
12
Test
Web Service
Failed
Successful
User Not
Get User
Found
Successful
Failed
Update User
Delete User
Failed
Successful
Successful
Success
Error
The following code will call the Yellowfin web service to edit a user.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
person.setFirstName("Simple 2");
person.setLastName("Simon 2");
person.setInitial("F");
person.setSalutationCode("DR");
person.setRoleCode("YFADMIN");
person.setEmailAddress("[email protected]");
rsr.setLoginId(this.username);
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
13
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("UPDATEUSER");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user update failed.
Retrieving User Information
Once a user has been created, the users details can be retrieved using a web
service call. The User Id field (in AdministrationPerson) is used to identify the user. A
populated AdministrationPerson object will be returned. Passwords will not be
returned. They will be null.
The following code will call the Yellowfin web service to retrieve a users details.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("GETUSER");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
person = rs.getPerson();
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
14
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user update failed. The person details
will be available in the person object.
Deleting a User
A Yellowfin user can be removed from the system via a web service call. The User Id
field (in AdministrationPerson) is used to identify the user. (See Manipulating Users
for workflow diagram)
The following code will call the Yellowfin web service to delete a user.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new
AdministrationPerson();
person.setUserId("admin");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("DELETEUSER");
rsr.setPerson(person);
rs =
AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user delete failed.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
15
Changing a Users Password
A Yellowfin users’ password can be changed from the system via a web service call.
The User Id field (in AdministrationPerson) is used to identify the user.
The following code will call the Yellowfin web service to change a users’ password.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new
AdministrationPerson();
person.setUserId("admin");
person.setPassword("newpassword");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("CHANGEPASSWORD");
rsr.setPerson(person);
rs =
AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the password update failed.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
16
Chapter 3 - Single Sign On
Overview
Single Sign On allows for users of Yellowfin to navigate seamlessly from the OEM
application to Yellowfin. The user only has to login into the OEM application, and
these details are kept for suppressing the Yellowfin logon screen when a user
navigates to the reporting section of the application.
Performing Single Sign On
The Yellowfin logon screen can be suppressed by using the Single Sign On web
service call. The web service call validates the users credentials and returns a login
token. This token can then be used on the end of the Yellowfin URL to allow the user
direct access to Yellowfin. Populating the OrgRef property will allow the user to be
logged into a Client Organisation. The OrgRef should be left as null if logging the user
into the Primary Organisation.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
17
The following code will call the Yellowfin web service to perform Single Sign On.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setOrgRef("CLIENTORG");
rsr.setFunction("LOGINUSER");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
String Token = rs.getLoginSessionId()
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the password update failed.
The Token can then be placed in the following URL to bypass the Yellowfin login
screen:
http://<yellowfin-server>/logon.i4?LoginWebserviceId=<LoginSessionId>
eg. http://localhost:8080/logon.i4?LoginWebserviceId=423AD1232DF3234234
Performing Single Sign On without a Password
It is also possible to perform Single Sign On without suppling a password. This may
be required when using LDAP to authenticate users, or when using other
mechanisms for user authentication where the password is not actually stored or
accessible by the OEM application. This functionality has to be enabled on each
instance of Yellowfin by adding a record to the Configuration table in the Yellowfin
database.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
18
iporg
configtypecode
configcode
configdata
1
SYSTEM
SIMPLE_AUTHENTICATION
TRUE
Yellowfin will need to be restarted for this functionality to be enabled. The following
code will call the Yellowfin web service to perform Single Sign On without requiring a
password for the user.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setOrgRef("CLIENTORG");
rsr.setFunction("LOGINUSERNOPASSWORD");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
String Token = rs.getLoginSessionId()
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the password update failed. The Token
can then be placed in the following URL to bypass the Yellowfin login screen:
http://<yellowfin-server>/logon.i4?LoginWebserviceId=<LoginSessionId>
eg. http://localhost:8080/logon.i4?LoginWebserviceId=423AD1232DF3234234
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
19
Web Service Logon Parameters
Parameters may be passed to the login process to modify the user's session.
Parameters take the form "key=value", and the following are valid parameters:
Key
Values
Description
Whether or not to show the toolbar (Dashboard,
yftoolbar
true/false
Create Report, Report List and Administration
links) on appropriate pages. Setting this option
overrides the system-wide configuration setting.
dashboard
reportlist
entry
createreport
administration
viewreport
reportid
reportname
ReportId
The initial page to redirect to upon login. The
user must have the necessary functional
access. The default is dashboard if the user has
dashboard access, otherwise reportlist. If set to
viewreport, the reportid or reportname must also
be set.
When entry=viewreport, this specifies the report
to view.
Report Object
When entry=viewreport, this specifies the report
Name
to view.
If this is set to true, source filters will be disabled
on all reports run by this user during the login
disablesourc
efilters
session. Only enable this for users who are
true/false
allowed to see all data unrestricted. Note: this
does not affect reports created against Stored
Procedures that use a source filter for one of the
parameters to the Stored Procedure.
If this is set to true, the page header will not be
hideheader
true/false
shown. Setting this option overrides the systemwide configuration setting.
If this is set to true, the page footer will not be
hidefooter
true/false
shown. Setting this option overrides the systemwide configuration setting.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
20
If this is set to true, the page left navigation will
hidesidenav
true/false
not be shown. Setting this option overrides the
system-wide configuration setting.
hidelogoff
true/false
reasoncode
reason
reasondescri
ption
reason
If this is set to true, the logoff links will not be
shown.
A reason code to include in events logged
during this user's session
A reason description to include in events logged
during this user's session
The Parameters attribute of the AdministrationServiceRequest is a String Array, and
can be populated with several parameters for a logon call.
The following code will call the Yellowfin web service to perform Single Sign On
without requiring a password for the user. This call also modifies the user's session so
that the user will be taken directly to the Administration page, and all source filters will
disabled for this user.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
String[] parameters = {
"entry=administration",
"disablesourcefilters=true"
};
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setOrgRef("CLIENTORG");
rsr.setFunction("LOGINUSER");
rsr.setPerson(person);
rsr.setParameters(parameters);
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
21
rs = AdministrationService.remoteAdministrationCall(rsr);
String Token = rs.getLoginSessionId()
Performing a Logoff via Web services
A Yellowfin session can be destroyed via web services. This allows for memory to be
freed when a users session has ended. A session will expire in the standard timeout
period, usually 20 minutes, so a Logoff is not entirely necessary.
There are two ways a log off can be performed. A user can be specified, and
Yellowfin will destroy all sessions for that user, or, the session id used to log the user
in via Single Sign On can be used to destroy one particular session.
The following code calls the Yellowfin web service to Logoff the user specified:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("LOGOUTUSER");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
22
The following code will call the Yellowfin web service to perform a Logoff with a
Session Id specified:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("LOGOUTUSER");
rsr.setLoginSessionId("423AD1232DF3234234");
rs = AdministrationService.remoteAdministrationCall(rsr);
In both cases, the code will return SUCCESS in the rs.getStatusCode() if successful,
otherwise it will return an error message explaining why the logout failed
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
23
Chapter 4 - Defining Functional Access
Overview
The functional access that each user has is defined by the Yellowfin Role assigned to
that person. Each Role is defined within the Yellowfin interface, and is a list of active
functions that allow users to perform different actions. Each user can only have one
role at a time, which can be assigned manually via the Yellowfin interface, or
automatically via web services.
Changing a Users Role via the Yellowfin Interface
Assign or modify a user's role from the User page from within the Yellowfin interface.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
24
Changing a Users Role via Web Services
Modify the Role of a user using the ADDUSER and UPDATEUSER functions.
Populate the AdministrationPerson object property RoleCode with the role that is to
be assigned the user. The RoleCode is the Code for the Role, not the Role
Description. Interrogate the Yellowfin database to obtain the RoleCode for a particular
role. This can be obtained from the Yellowfin Database Table, OrgRole.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
25
Chapter 5 - Row Level Security
Overview
The use of source filters allows for data to be restricted at the row level based on the
user who is running the report. It is implemented by defining a relationship between a
user and data values in the database. The relationship is assigned to a database
column which will then restrict rows returned where the data values match the data
assigned to the current user.
The relationship between users and data can be maintained via manual entry, a file
upload, or automatically via a scheduled SQL job against the source database.
The type of relationship required for a source database is based on the how complex
the user configurations are in the OEM application. If the users in the OEM
application are relatively static then it may be possible to manage the relationships
manually. If the OEM application contains functionality to create, modify and delete
users then it may be better to automate the relationship generation in Yellowfin. Most
OEM applications will require automatic generation of relationships within Yellowfin.
That is what will be covered in the chapter.
Prerequisites
To use source filters on particular data source, the username of the user must be
contained with the database. This is so a query can join between username and the
rows that they have access too, to generate the relationship between the user and
data.
Assigning a Relationship between a User and Data Values
Multiple relationships can be defined within each instance of Yellowfin. To enable
source filters on a data source, enable the Source Filters option on the data source
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
26
page. This will create a new step in the data source creation wizard called Filters.
The method for defining the source filters can then be chosen. This chapter will
outline the use of a scheduled SQL query to manage the relationships automatically.
Firstly, a Filter Type must be created. Each Filter Type defines a different relationship
between a user and data values. Filter Types are created from Available Filter Type
box on the right. In this example the Filter Type “DataRelationship” has been created.
This has been given the code “RLTSHP”. This code will be used in the SQL query
used to dynamically update the user's relationships.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
27
Once a filter has been defined, a SQL query can be written. The query must return
four columns from the source database. These columns must be:
User Type Code
User Identifier
Filter Type Code
Data Value
Here is an example of the types of data that could be returned in these columns:
User Type Code
User Identifier
Filter Type Code
Data Value
USERID
[email protected]
RLTSHP
6
USERID
Admin
RLTSHP
AU
YFPERSONID
5
RLTSHP
7
EMAIL
[email protected]
RLTSHP
STORE_A
It is important to remember that this data will be extracted from the current source
database. Usually SQL will be constructed to make use of the OEM application's
internal user to data relationships. This may involve joining to multiple tables to get
the correct relationships.
For example, a source database may have a User table and a UserStore table. The
User table stores the usernames (which can be used as a Yellowfin username) and
the UserStore table maintains the relationship between each User and the Stores that
they are related to.
The schema for these tables may look like this:
User Table
UserStore Table
UserId
UserId
UserName
StoreCode
FirstName
LastName
DateOfBirth
The SQL to retrieve each user's relationship to a store would be:
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
28
SELECT 'USERID', a.UserName, 'RLTSHP', b.StoreCode
FROM User a
INNER JOIN UserStore b ON (a.UserId = b.UserId)
Note that 'RLTSHP' is the Filter Type Code defined within Yellowfin.
If one user has relationships to multiple stores, then it will return a row for each store.
This is a valid result.
Validating that the SQL Query is Correct
Once a SQL query has been refreshed, Yellowfin should list the users and the data
associated with each user. The list of users and values is available from the bottom of
the Source Filter page. If the list contains no results, it may mean that the User fields
in the SQL results not correctly matching a current Yellowfin user.
Scheduling Source Filters to Update Automatically
Once a SQL query has been constructed to bring back the Source Filter relationships
for Yellowfin users, it can be scheduled to be run in the background on a scheduled
basis. The schedule section of the Source Filter page, allows the SQL to be
scheduled at a particular intervals.
It may also be beneficial to enable the “Refresh filter when new Yellowfin users are
created” option. This will run the source filter when a new user is created so that
relationships are generated for that user immediately.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
29
Assigning a Source Filter to a View Field
After a Source Filter has been defined, it can then be assigned to a particular field in
a Yellowfin view. On the View Fields page, double clicking a field will load the details
for that field. On the Access tab there is an option to select the Source Filter that
should be assigned to this field. Click the Save link to apply the changes.
From the Security page, there is an option to make the applied Source Filter the
default filter. This will mean that all reports written against this view will automatically
filter based on the Source Filter applied, and restrict the data based on the Yellowfin
user viewing the report.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
30
Chapter 6 - Report Level Security
Overview
Access can be granted to users to see certain categories of reports within Yellowfin.
Access is granted on a per group or user basis. Users can be manually added or
removed from groups through the Yellowfin interface, or programmatically via web
services.
Access Level Security on Report Subcategories
For OEM clients report security can be defined by groups. It is recommended that
group security be used (rather than user level security) as groups can be exported
and imported between client systems, keeping security portable.
Group security can be applied to a subcategory via the Yellowfin interface.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
31
Once a report category is assigned group security, Administrators can then add and
remove users from these groups via the Yellowfin interface or they can be modified
via Yellowfin web service calls from the OEM application.
Assigning Users to Groups via the Yellowfin Interface
Add and remove users from groups via the Group Management interface available
from the Administration page. Groups can also contain other groups.
Groups can be defined by including or excluding Yellowfin Users, members of Roles
or members of other Yellowfin groups. Remove members from the group by clicking
the checkbox next to the member name.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
32
Assigning Users to Groups via the Yellowfin Web service
To include a user in a group execute the following:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
rsr.setLoginId(this.username);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("INCLUDEUSERINGROUP");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
33
To exclude a user from a group execute the following:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
rsr.setLoginId(this.username);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("EXCLUDEUSERFROMGROUP");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
To remove a user entry from group definition:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson person = new AdministrationPerson();
person.setUserId("admin");
person.setPassword("password");
rsr.setLoginId(this.username);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("DELUSERFROMGROUP");
rsr.setPerson(person);
rs = AdministrationService.remoteAdministrationCall(rsr);
In all cases, the code will return SUCCESS in the rs.getStatusCode() if successful,
otherwise it will return an error message explaining why the logout failed.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
34
Retrieving Group Members via the Yellowfin Web service
Group Members can be retrieved via the Yellowfin interface. This will only return the
flattened members from the group, not the group definitions.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationGroup group = new AdministrationGroup();
group.setGroupName("Group Name");
rsr.setLoginId(this.username);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("GETGROUP");
rsr.setGroup(group);
rs = AdministrationService.remoteAdministrationCall(rsr);
group = rs.getGroup();
AdministrationGroupMember[] GroupMembers =
group.getGroupMembers();
Group Members will be returned as an array of AdministrationGroupMember records,
within the AdministrationGroup object return in the AdministrationServiceResponse
object.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
35
Chapter 7 - Client Organisation Functionality
Overview
Yellowfin features functionality called “Client Organisations” which allows multiple
virtual instances of Yellowfin to reside in the same server instance. This allows
content to be created and segregated from other organisations logging onto the same
Yellowfin server. Client Organisation functionality operates on a two-tier basis. The
top tier, known as the Primary Org (default), can have content that is shared between
all Client Organisations. Content created at the second-tier will not be visible to any
other second-tier instances of Yellowfin.
Users can be given access to log in to the default organisation and/or one or more
client organisations. Content such as data sources, reports and dashboards can
belong to either the default organisation or one of the client organisations. When a
user logs in to an organisation (default or client), any content they create “belongs” to
that organisation.
Yellowfin's Client Organisation functionality is managed completely by web services.
Web services exist to create and delete Client Organisations from Yellowfin. Other
web services allow for the management of users in regards to Client Organisation
access and logging the user into a particular Client Organisation.
There is an example JSP file in the Development directory, in the Yellowfin installation
directory. The JSP is called “ws_admin_clientorgs_api.jsp”. This can be copied to the
Yellowfin/appserver/webapps/ROOT directory and accessed via the browser. This
page features most of the functionality required to use Client Organisations, but it is
not for production use without modification as it is not protected by authentication.
The functionality should ideally be replicated in a standalone application or integrated
into the OEM application.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
36
Creating a Client Organisation
A web service call is required to generate a new Client Organisation. An
AdministrationClientOrg object should be populated, attached to the
AdministationRequest, and sent to Yellowfin.
The following code will call the Yellowfin web service to create a Client Organisation:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationClientOrg client = new
AdministrationClientOrg();
client.setClientName("Client Org A");
client.setClientReferenceId("ORG_A");
client.setTimeZoneCode("AUSTRALIA/SYDNEY");
client.setDefaultOrg(false);
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("CREATECLIENT");
rsr.setClient(client);
rs = AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
Deleting a Client Organisation
A web service call is required to delete an existing Client Organisation. An
AdministrationClientOrg object should be populated, attached to the
AdministationRequest, and sent to Yellowfin.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
37
The following code will call the Yellowfin web service to delete a Client Organisation:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationClientOrg client = new
AdministrationClientOrg();
client.setClientReferenceId("ORG_A");
client.setDefaultOrg(false);
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("DELETECLIENT");
rsr.setClient(client);
rs = AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
Modifying a Client Organisation
A web service call can modify Client Organisation after it has been created. An
AdministrationClientOrg object should be populated, attached to the
AdministationRequest, and sent to Yellowfin. The ClientReferenceId is required to
lookup the Client Org, and hence this cannot be changed.
The following code will call the Yellowfin web service to modify a Client Organisation:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationClientOrg client = new
AdministrationClientOrg();
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
38
client.setClientName("Client Org B");
client.setClientReferenceId("ORG_A");
client.setTimeZoneCode("AUSTRALIA/SYDNEY");
client.setDefaultOrg(false);
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("UPDATECLIENT");
rsr.setClient(client);
rs = AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
Listing all Client Organisations
A web service call can retrieve all Client Organisations existing within an instance of
Yellowfin. The results will be returned in a list of AdministrationClientOrg objects.
The following code will call the Yellowfin web service to retrieve a list of all available
Client Organisations:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationClientOrg[] clientList = null;
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("LISTCLIENTS");
rs = AdministrationService.remoteAdministrationCall(rsr);
clientList = rs.getClients();
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
39
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
Retrieving a Client Organisation
A web service call can retrieve a Client Organisation after it has been created. The
ClientReferenceId is required to lookup the Client Org, and a fully populated
AdministrationClientOrg object will be returned by the web service.
The following code will call the Yellowfin web service to retrieve a Client Organisation:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationClientOrg client = new
AdministrationClientOrg();
client.setClientReferenceId("ORG_A");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("GETCLIENT");
rsr.setClient(client);
rs = AdministrationService.remoteAdministrationCall(rsr);
client = rs.getClient();
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
List Users Who Have Access to a Client Organisation
A web service call can retrieve all the Yellowfin Users who have acces to a particular
Client Organisation. The ClientReferenceId is required to lookup the Client Org, and
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
40
an array of populated AdministrationPerson objects will be returned by the web
service.
The following code will call the Yellowfin web service to retrieve all users who have
access to a Client Organisation:
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson[]
people = null;
AdministrationClientOrg client = new
AdministrationClientOrg();
client.setClientReferenceId("ORG_A");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("LISTUSERSATCLIENT");
rsr.setClient(client);
rs = AdministrationService.remoteAdministrationCall(rsr);
people = rs.getPeople();
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
List Client Organisations accessible by a User
A web service call can retrieve all the Client Organisations that are accessible by a
particular User. The UserId is required to lookup the User, and an array of populated
AdministrationClientOrg objects will be returned by the web service.
The following code will call the Yellowfin web service to retrieve all the Client
Organisations that are accessible by a User:
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
41
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson
user = new AdministrationPerson();
AdministrationClientOrg[] clients = null;
user.setUserId("[email protected]");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("GETUSERACCESS");
rsr.setPerson(user);
rs = AdministrationService.remoteAdministrationCall(rsr);
clients = rs.getClients();
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
Grant User Access to a Client Organistion
Each user will need to be granted access to a Client Organisation via a web service
call. The UserId is required to specify the User, and a Reference Id is required to
specify the Client Organisation in which to grant access.
The following code will call the Yellowfin web service to grant access to Client
Organisations for a particular user.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson
user = new AdministrationPerson();
AdministrationClientOrg client = new
AdministrationClientOrg();
user.setUserId("[email protected]");
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
42
client.setClientReferenceId("ORG_A");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("ADDUSERACCESS");
rsr.setPerson(user);
rsr.setClient(client)
rs = AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
Remove User Access to a Client Organistion
Each user can be denied access to a Client Organisation via a web service call. The
UserId is required to specify the User, and a Reference Id is required to specify the
Client Organisation in which to grant access.
The following code will call the Yellowfin web service to remove access to Client
Organisations for a particular user.
AdministrationServiceRequest rsr = new
AdministrationServiceRequest();
AdministrationServiceResponse rs = null;
AdministrationPerson
user = new AdministrationPerson();
AdministrationClientOrg client = new
AdministrationClientOrg();
user.setUserId("[email protected]");
client.setClientReferenceId("ORG_A");
rsr.setLoginId(this.username);
rsr.setPassword(this.password);
rsr.setOrgId(PRIMARYORG);
rsr.setFunction("REMOVEUSERACCESS");
rsr.setPerson(user);
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
43
rsr.setClient(client)
rs = AdministrationService.remoteAdministrationCall(rsr);
This code will return SUCCESS in the rs.getStatusCode() if successful, otherwise it
will return an error message explaining why the user creation failed.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
44
Chapter 8 - Application & UI Integration
Overview
Options for interface integration range from having a simple link on an existing
corporate portal to the Yellowfin server through to full Web Services integration that
allows reports to be delivered into an application with maximum control of look and
feel. This chapter focus on configurable integration options. More advanced options
using web services are dealt with in a subsequent chapter of this guide.
Frames based integration
In addition to customising the style-sheets, Yellowfin can be customised to remove all
header and side navigation elements – this provides for seamless integration into a
frames-based intranet. If the application or intranet doesn’t use frames (eg. web
portals such as Sharepoint, Websphere, etc) an IFRAME can be used instead – this
operates in a similar manner to a frame however can be embedded into a portal to
retain the standard functionality of the portal (navigation, etc).
Benefits:
• Rapid deployment.
• More consistent look & feel.
• Low integration effort.
• Low integration complexity.
• Participates in the navigation framework.
Drawbacks:
• Frames are not highly recommended / used.
• Not appropriate for non-web applications.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
45
Portal / Application Links
Existing Navigation
Side Frame
Top frame
Yellowfin runs in central
frame, all required links
are internal.
Yellowfin runs
embedded in page.
Better usability and
adherence to existing
look and feel.
Portal / Application Links
Traditional Frames approach.
Web page IFRAME approach.
Custom Header & Navigation
The Yellowfin application can be integrated into existing or new applications by
removing or replacing the side and top navigation areas. Doing this will replace the
navigation uniformly across all Yellowfin pages.
Replacing the navigation with an html fragment allows the quick addition of site links
to each page. Customising the navigation areas is a quick and easy way to integrate
Yellowfin into the application, while preserving full functionality.
Benefits:
• Rapid deployment.
• More consistent look & feel.
• Low integration effort.
• Low integration complexity.
• Participates in the navigation framework.
Drawbacks:
• Removal of side nav will impact usability
• Not appropriate for non-web applications.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
46
Embeddable Java Client
The client component of Yellowfin can be deployed as simple java library (JAR file)
into the GUI or web java application. This client component provides a set of APIs
that will connect to a Yellowfin Server using Web Services and render the returned
report (including tables, drill downs, graphs, etc) within the application. Integration
can be achieved with minimal coding.
Benefits:
• Full control over look & feel.
• Supports both java web & GUI applications.
• Low to medium integration effort.
• Medium integration complexity.
• Report development is abstracted from the application - additional reports can be
added through the server
• Utilises Web Services to communicate with the server.
Drawbacks:
• More effort for initial integration.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
47
Web Services Integration
For non-java applications or web applications that require a more complete control
over look-and-feel, Yellowfin provides a Web Services interface to browse the list of
reports and to execute reports. All elements (table data, graph images, etc) are
returned as fields to allow for fully customised layout of the reports within the
application framework.
Web Services also receives raw report data from Yellowfin, allowing the data to be
rendered into the existing application’s reports, or exported in other formats. This
Web Services interface is the same one used by the embeddable client. The report is
then rendered with the aid of the Yellowfin embedded java client or by the application
- note that this may be a very simple or complex depending on the requirements (eg.
The simplest scenario would involve returning all requested reports in PDF format
which could just be passed straight through with no additional rendering).
Benefits:
• As per the embeddable client.
• Supports .net and other non-java programming languages (eg. PHP, C++, etc)
Drawbacks:
• More effort for initial integration.
Existing
Intranet /
Portal
Web Services call
Yellowfin
Yellowfin
Web
Services
Application
Server
Server
Yellowfin
Yellowfin
Database
Database
Existing / OEM
Existing / OEM
Application
Application
Corporate
Corporate
Directory
Directory
Using web services the existing application is delivered report lists and report content through a
remote program call.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
48
Inline System Integration
The Yellowfin application can be integrated into existing or new applications by
removing or replacing the side, top navigation and footer areas. Doing this will replace
the navigation uniformly across all Yellowfin pages. Replacing the navigation with an
html fragment allows the quick addition of customised site links to each page.
Removing the navigations may be suitable for including Yellowfin in an html frame
inside the application. Customising the navigation areas is a quick and easy way to
integrate Yellowfin into the application, while preserving full functionality.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
49
Navigation Replacement & Functionality
Removing or replacing navigation has to be evaluated based upon the user actions
within Yellowfin.
Top Navigation – Page Header
The Yellowfin top navigation area has been left intentionally blank. The only
functionality is the log-off link. As such replacing this navigation area will have little
impact on the usability of Yellowfin.
Left Navigation
The left side Navigation is used within Yellowfin. However, it is generally a redundant
element since if it is in use it will also be done so in conjunction with the standard
wizard steps. However, some users do tend to use the side navigation over the
wizard steps. The one place where the side nav is used without the wizard is on the
report preview page. The user would have to use the edit drop down to navigate
back to the report data page.
Customising Navigation Areas
1. To customise the navigation areas, the user must be logged in with a role that has
access to the Configuration page.
2. Go to the Administration section, and click on the Configuration link. For the top
navigation, the available options are:
Standard Yellowfin
Use the standard Yellowfin header on every page. This
Header
includes the title of the page, and a link to log the user off.
No Header
Do not include any header.
Custom Header
Use a custom header.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
50
3. Select Custom Header from the list as shown below.
Page Header Update
4. A Custom URL will need to be entered. This is a link to an html fragment that will
be included at run-time every time a page is loaded. The fragment can be located
on any server that the Yellowfin server can access, but for best performance, it
should be connected via a fast link. Ideally, the included html fragment would be
hosted on the same server as Yellowfin.
The easiest way to host the html fragment (and the only way if there is no separate
web server) is to store it in the Yellowfin program directory:
eg. C:\Program Files\Yellowfin\appserver\webapps\ROOT\header.html
This fragment will then be available via the URL: http://localhost/header.html
The included html should be an html fragment, suitable for including inline within
another html page, rather than a full html document. That is, it should not contain
<html>, <head> or <body> tags. Remember that any links inside the html will be
relative to the Yellowfin page. It is recommended to use absolute URL links
It is also important to remember that the standard Yellowfin header provides the
only link for a user to log out of the system. If the header is being replaced provide
a link to log off by the URL: javascript:on_submit(‘logoff’);
This link will log the user off from any Yellowfin page.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
51
Customised Toolbar
Yellowfin allows the creation of a customised tool bar which replaces the existing tool
bar. This is a useful way to change the look and feel of the tool bar – eg create
buttons or add additional links for functionality.
To get this to work an include file must be created, which contains the same links as
the Yellowfin toolbar – and any additional needed for the application. Because these
links are not always displayed in Yellowfin there is a parameter that can be passed to
the application to determine whether the toolbar should be showing or not. Yellowfin
will pass the parameter "yftoolbar" to the custom header, and it'll be set to "true" on
pages where the toolbar links would normally be shown.
eg. header.jsp?yftoolbar=true
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
52
Chapter 9 - Silent Installer
Overview
Yellowfin generally is installed via its own branded installer. However, the use of a
silent installer allows Yellowfin to be wrapped into the existing application’s installer,
deploying “silently” in the installation process.
The installers would essentially be a wrapper around the Yellowfin silent installer.
The installer will create the Yellowfin database and aggregate information about the
application. This aggregated information gets inserted into some properties files
which enable clients to create the data sources OOTB on the installation. Yellowfin
provides a command line java process to do this.
The installation process may also invoke the content import (another java procedure)
to pre-load content on installation and by calling the deployment descriptor include
the Yellowfin database connection details.
In additional to this, initialisation steps can be performed on the start up of the
application. On start up, make sure that the configuration settings are correct
(dashboard width, custom header, support email address, etc.). Permissions for roles
can also be set in a customisable way. For example, because users may be created
in the existing system, and then only create users in Yellowfin on Single Sign On,
disallow the use of the UI to create/modify/delete users, groups, or roles. This allows
all user administration to remain within the existing product.
Download the silent installer jar
The silent command-line installer is available for download please contact Yellowfin to
get the latest version.
1. It can be run using the following command from the command line:
java -jar <yfsilentinstall-file name>.jar install.properties.txt
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
53
2. Ensure that the properties options are specified via the associated properties file.
3. If successful, it won't print anything out and exits with return code 0.
4. On error, an error message will be printed out and a non-zero value returned. The
installation process will be logged in more detail to a file in the installation directory
(specified in the properties file).
Silent Installer Properties File
# Yellowfin silent installer properties file
# Properties for installer:
# Java Home path - Not required. Defaults to the current JVM home.
#
#JavaHome=C:/j2sdk1.4.2
#JavaHome=/usr/local/j2sdk1.4.2
# Installation path - Required.
#
#InstallPath=C:/Program Files/Yellowfin
#InstallPath=/usr/local/Yellowfin
InstallPath=C:/Program Files/Yellowfin
# Install Tutorial Database? - Not Required. Defaults to True.
# Options: True, False
#
InstallTutorialDatabase=True
# Licence File - Not required, but user will need to upload on first login to
Yellowfin.
#
#LicenceFilePath=C:/Licence.lic
#LicenceFilePath=/home/peter/Licence.lic
# TCP Port - Not Required. Will default to Port 80 if none specified.
#
ServicePort=8080
# Install a system service? - Not required. Windows only. Defaults to False.
# Options: True, False
#
#InstallService=True
# Yellowfin Database Type - Required
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
54
# Options: SQLServer, MySQL, Oracle, PostgreSQL, DB2, Ingres, Progress
#
DatabaseType=PostgreSQL
# For SQL Server Only: SQL Server Authentication or Windows Authentication. Not
Required, Default "SQL"
# Options: SQL, Windows
#
#Authentication=SQL
# For SQL Server Only: Windows Authentication Logon Domain name. Required if
Authentication=Windows.
#
#LogonDomain=WorkGroup
# For Progress Only: Path to Client Networking tools for JDBC Type 2 driver.
#
#ProgressDriver=/usr/dlc/java/jdbc.jar
# Create new Yellowfin DB / or use existing - Not required. Default True.
# Options: True, False
# Note: database creation is only supported for the following DatabaseTypes:
#
MySQL
#
SQLServer
#
PostgreSQL
#
For other databases, this property is ignored.
#
CreateYellowfinDB=True
# Create new tables in the Yellowfin DB - Not required. Default True.
# Options: True, False
# Note: This property is only used if CreateYellowfinDB is False.
#
#CreateYellowfinTables=True
# Create new Yellowfin User or use existing - Not required. Default True.
# Options: True, False
# Note: user creation is only supported for the following DatabaseTypes:
#
MySQL
#
SQLServer
#
#
PostgreSQL
For other databases, this property is ignored.
#
CreateYellowfinDBUser=False
# Database Hostname/Ip Address - Not Required. Default "localhost"
#
DatabaseHostname=localhost
# Database Port - Not required, will use default for specified DB.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
55
#
#DatabasePort=1433
# Database Name - Not required, will default to "Yellowfin"
#
DatabaseName=yellowfin
# Database DBA Username - Required.
#
DatabaseDBAUser=system
# Database DBA Password - Required.
DatabaseDBAPassword=
# Database Yellowfin User - Not Required, will default to "YellowfinUser"
DatabaseUser=yellowfin
# Database Yellowfin User Password - Not Required, will default to "password"
DatabasePassword=
Error Messages
The silent installer will output all error messages to stderr, and will return non-zero
return codes for specific errors.
Error Codes:
1 – Properties file not specified.
2 – Could not parse properties file.
3 – Installation path is not a directory, or could not be created.
4 – Unable to create log file.
5 – There is no error number 5.
6 – Installation process has failed.
7 – Installation of the tutorial database has failed.
Once the installation has started all activity will be logged to the installation log file in
the installation directory.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
56
Deploying inside the Yellowfin tomcat container.
Deploying the existing application within the same tomcat container as Yellowfin
means that the code is deployed into the same location as Yellowfin.
Additional JSP pages will be put into Yellowfin/appserver/webapps/ROOT and
additional compiled code can be placed in Yellowfin/appserver/webapps/ROOT/WEBINF/classes or Yellowfin/appserver/webapps/ROOT/WEB-INF/lib (if they are compiled
to libraries).
Deploying the application with Yellowfin means that Yellowfin code can be used for
accessing the Yellowfin database and Yellowfin internal objects. This is not
documented as there are approximately 20,000 public functions that can be called
from inside Yellowfin.
Please consult the user forum or support on what data will need to be accessed in
Yellowfin.
If the application is to be deployed in Yellowfin it is good to know how to use the struts
framework. Visit http://en.wikipedia.org/wiki/Apache_Struts to learn about struts, this
is how navigation and form data is managed in Yellowfin.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
57
Chapter 10 - LDAP
Overview
Yellowfin can be connected to an LDAP source for authentication and group
management purposes. This allows Yellowfin access to be controlled externally and
organisation-wide simply and quickly. Users can use their existing intranet password
for Yellowfin authentication and reports can be given access restrictions which
include or exclude users in specific LDAP groups.
Yellowfin has the option to reference an external directory (LDAP) or database to
perform authentication of an entered user id. Without single sign-on, this means that
a user will have the same user id and password across all participating applications
that use the directory. In addition, removal / lockout of the user on the directory will
automatically flow through to Yellowfin, hence minimising the manual effort to
manage users.
Preparing LDAP Integration
Prior to setting up the LDAP parameters in Yellowfin the following will have to be
completed:
1. Create a Yellowfin User (or specify an existing user) within the LDAP to allow
Yellowfin to connect and search for users and groups.
2. Create a ‘Yellowfin User’ Group within LDAP (or specify one) which will be used
to determine which users within LDAP will have access to Yellowfin.
3. Ensure network connectivity between the Yellowfin server and the LDAP server.
4. Define the default Yellowfin role for LDAP users.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
58
Defining the Default Role
For Yellowfin to provision users automatically it has to assign a role for them. This
role is defined as a Yellowfin ‘Default’ role. In the role management section of the
administration panel define one Role as the organisational default.
1. Open role management from the administration panel within Yellowfin.
Role Management List
2. Select the role that to make the default role by clicking on the hyper linked name.
This will open the role for edit purposes.
3. Tick the Default Role check box.
Role Management Form
Note: If no role is set as default the users will not be provisioned correctly into
Yellowfin and the process will fail.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
59
Users Provisioning and Sign-on
To provision users from the LDAP directory and to use LDAP authentication specify
the LDAP attributes in the Yellowfin Administration and configuration section.
The attributes required by Yellowfin include:
Property
Description
LDAP Host
LDAP server hostname or IP address
LDAP Port
TCP/IP port that the LDAP server is listening on.
LDAP Base
Base DN under which all Yellowfin users and groups are
Distinguishing
connected.
Name
LDAP Yellowfin
LDAP Group Name of which all users that are allowed to
User Group
login are members of. This group exists in the LDAP
directory. It is not a Group created within the Yellowfin
application.
LDAP Binding User
This is a LDAP User that the Yellowfin application uses to
connect to the LDAP directory for search access
LDAP Binding User
The LDAP Password required for the Yellowfin application to
Password
connect to the LDAP.
LDAP Search
This is unique ‘user name’ field that LDAP users will use as
Attribute
their Login into Yellowfin. This is an LDAP parameter such as
Email address or Employee Number.
First Name
This maps to the first name attribute of the user within the
Attribute Name
LDAP directory. This is so Yellowfin can match the user to a
name and create an internal user account.
Surname Attribute
This maps to the surname attribute of the user within the
Name
LDAP directory. This is so Yellowfin can match the user to a
name and create an internal user account.
Email Attribute
This maps to the email address attribute of the user within
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
60
Name
the LDAP directory. This is so Yellowfin can match the user
to an email address for broadcast reports.
Once defined Yellowfin will automatically provision users as they attempt to login to
Yellowfin for the first time.
Note: If the users in LDAP exceed the number of licenses purchased any new users
will not be provisioned into the system.
Example
This is an example taken from the Configuration page of the Yellowfin database.
The configuration above will connect to a LDAP host 192.168.4.241 on port 389.
Users will be searched from cn=Users,dc=i4,dc=local.
Users will be allowed access to Yellowfin if they are a member of
cn=Yellowfin Users,cn=Users,dc=i4,dc=local.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
61
The user search is conducted with user
cn=Administrator,cn=Users,dc=i4,dc=local bound to the LDAP server with
password password.
Users will use employeeID as there login ID and Yellowfin will load their given name,
surname and email from the LDAP directory attributes givenName, LastName,
userPrincipalName respectively.
If a user is not found in the LDAP directory, it will look for the username as a standard
Yellowfin user.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
62
Using LDAP Groups for Yellowfin Security
Once LDAP authentication is enabled, the Group Management screens will include a
new group option called “LDAP”. This will source groups from the LDAP directory for
use as normal Yellowfin groups. Yellowfin groups can also be created based on a
variety of sources including mixtures of LDAP and Yellowfin groups, where LDAP
groups can be either included or excluded in the new group.
1. Choose LDAP Group from the Member type drop down.
2. A list of all LDAP groups will be displayed. Select the group to be used to create
members for the Yellowfin Group.
3. Click Add members to add the LDAP group members into the Yellowfin Group.
LDAP Group Selection
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
63
Chapter 11 - Out of the Box Content
Overview
This chapter is specifically for OEM users who wish to deploy reporting content out to
their clients and manage that content on an ongoing basis. One of the main
considerations when integrating Yellowfin will be the out of the box (OOTB) content
that is provided to clients. The content that can be shipped includes Data sources,
Yellowfin Views, Tabs, Categories, and Reports.
Users are able to manually create the content in their own application. This means
they are able to create a data source against their data mart, users create the
categories and views and reports, applied with security. All content created is
exportable via an XML file and can either be imported manually through the Yellowfin
UI or via a command line procedure.
Typically Yellowfin would be deployed with a reasonable number of reports and tabs
to meet the client’s basic needs. However, since Yellowfin does have advanced ad
hoc report writing capability not all reports need to be delivered to clients, since they
will be able to create new reports and easily alter existing ones themselves.
The amount of time required for the development of OOTB content is largely
dependent on the complexity of the application. The more complex the application
the longer this phase will take.
Command Line Data Source Creation
The Yellowfin command line data source creation process can be used to deploy out
of the box content directly from the installer.
To create a data source run the following java command:
java com.hof.standalone.util.CreateDataSource <propertiesfile>
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
64
The properties file contains connection details for the Yellowfin configuration
database, as well as the details of the data source to be created. See the example
properties file below - datasource.properties.txt. Please note that the classpath will
have to be set up to include the Yellowfin libraries.
datasource.properties.txt
# Properties for datasource creation process
#
# Comments start with #
##############################################
# Yellowfin configuration database details
# This section contains connection details for the Yellowfin configuration
# database.
# Yellowfin Database Type - Required
# Options: SQLServer, MySQL, Oracle, PostgreSQL, DB2, Ingress, Progress
#
DatabaseType=SQLServer
# For SQL Server Only: SQL Server Authentication or Windows Authentication.
Not Required, Default "SQL"
# Options: SQL, Windows
#
#Authentication=SQL
# For SQL Server Only: Windows Authentication Logon Domain name. Required if
Authentication=Windows.
#
#LogonDomain=WorkGroup
# Database Hostname/Ip Address - Not Required. Default "localhost"
#
DatabaseHostname=localhost
# Database Port - Not required, will use default for specified DB.
#
#DatabasePort=1433
# Database Name - Not required, will default to "Yellowfin"
#
DatabaseName=Yellowfin
# Database Yellowfin User - Not Required, will default to "YellowfinUser"
#DatabaseUser=yfuser
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
65
# Database Yellowfin User Password - Not Required, will default to "password"
#DatabasePassword=password
#
##############################################
##############################################
# Data source details
# This section contains connection details for the data source to be
# created.
# Datasource Name - Required
#
DataSourceName=travelution
# Datasource Description - Required
#
DataSourceDescription=travelution
# Maximum Rows Returned - Not Required, Default=0 (Unlimited)
#
#MaximumRows=0
# Datasource Timezone -
Not Required, will default to Yellowfin Server
Timezone.
# Otherwise accepts TIMEZONE Refcode.
#
#TimeZone=AUSTRALIA/SYDNEY
# Datasource Access Level - Not Required, Default "UnSecure"
# Access Level will not be implemented in commandline program initially.
#
#AccessLevel=UnSecure
# Datasource Broadcast Enabled - Not Required, default "False"
# Options: True, False
#
BroadcastEnabled=False
# Datasource Subscribe Enabled - Not Required, default "False"
# Options: True, False
#
SubscribeEnabled=False
# Datasource Source Filter Enabled - Not Required, default "False"
# Options: True, False
# (Source filter records can be uploaded by via import)
#
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
66
#SourceFilterEnabled=False
# Datasource Composite View Store Enabled - Not Required, default "False"
# Options: True, False
#
CompositeViewEnabled=False
# Connection Method - Required
# Options: JDBC, XMLA
#
ConnectionMethod=JDBC
# Connection Driver - Required if ConnectionMethod="JDBC"
# This is the JDBC driver name
#
ConnectionDriver=com.mysql.jdbc.Driver
# Connection URL - Required;
# This is the JDBC or XMLA Database URL.
#
ConnectionURL=jdbc:mysql://host/db
# Connection URL - Required if ConnectionMethod="XMLA"
# This is the XMLA Datasource
#
#ConnectionDatasource=
# Connection Catalog - Not Required - Default "" (Blank String)
# This is the XMLA Datasource
#
#ConnectionCatalog=
# Connection User - Not Required - Default "" (Blank String)
#
#ConnectionUser=yfuser
# Connection Password - Not Required - Default "" (Blank String)
#
#ConnectionPassword=password
# JDBC Minimum Connections - Not Required - Default 1
#
MinConnections=1
# JDBC Maximum Connections - Not Required - Default 5
#
MaxConnections=3
# JDBC Connection Recycle Time - Not Required - Default 3 (Hours)
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
67
#
RefreshTime=3
# JDBC Connection Timeout - Not Required - Default 180 (Seconds)
#
Timeout=180
#
##############################################
Command Line Report definition XML importer
Yellowfin command line XML importer process can also be used to deploy out of the
box content direct from the installer. To import data run the following java command:
java com.hof.standalone.util.ImportData <propertiesfile> <datafile>
The properties file contains connection details for the Yellowfin configuration
database. See the example file import.properties.txt. The data file is an xml file
exported through the Administration export page.
import.properties.txt
# Properties for import process:
#
# Comments start with #
# Yellowfin Database Type - Required
# Options: SQLServer, MySQL, Oracle, PostgreSQL, DB2, Ingress, Progress
#
DatabaseType=PostgreSQL
# For SQL Server Only: SQL Server Authentication or Windows Authentication.
Not Required, Default "SQL"
# Options: SQL, Windows
#
#Authentication=SQL
# For SQL Server Only: Windows Authentication Logon Domain name. Required if
Authentication=Windows.
#
#LogonDomain=WorkGroup
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
68
# Database Hostname/Ip Address - Not Required. Default "localhost"
#
DatabaseHostname=localhost
# Database Port - Not required, will use default for specified DB.
#DatabasePort=1433
# Database Name - Not required, will default to "Yellowfin"
DatabaseName=yellowfin
# Database Yellowfin User - Not Required, will default to "YellowfinUser"
#DatabaseUser=yfuser
# Database Yellowfin User Password - Not Required, will default to "password"
#DatabasePassword=
Setting up report categories
When setting up report categories it is useful to have a set that are pre-defined as
custom. For example deploy Yellowfin with a set of categories which no client user
can write to directly. They can copy reports out of the folders but not modify or add
new ones in. This means there can be a set of processes which can manage and
update this content and be certain that end user created content is not over written or
deleted.
Report Migration
If Yellowfin has been shipped with Out Of The Box Content and the content needs to
be replaced the migration process should be considered. Firstly ensure that users
cannot create or add content into defined reporting categories. Export dashboard tabs
and reports using the standard export process. See the admin guide. Note that the
matching process uses the name of the tab and reports as the key for replacement.
Ensure that the tabs and reports have the same names as those that to be replaced.
When loading content into the client site there will be a prompt to replace reports or
tabs with the same name, this process can be skipped if needed. If using the
Command Line Tool to import content there is a replace all content flag in the
properties file. The option is called ‘Replace All’ and the option is Yes/No. Set to Yes
to replace content.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
69
Appendix A – Web Services Further Information
Yellowfin Java Web Services API
When using the Yellowfin Java Web Services API, the relevant functions in the
AdministrationServiceClient class are:
listClients()
getClient(AdministrationClientOrg)
createClient(AdministrationClientOrg)
deleteClient(AdministrationClientOrg)
updateClient(AdministrationClientOrg)
getUserAccess(AdministrationClientOrg)
getUserAccess(AdministrationPerson)
A client organisation is represented by the AdministrationClientOrg object. This object
contains the organisation name, a unique Reference Id, the organisation's local
timezone, and a flag denoting whether the object represents the default organisation
or a client. For example, the listClients() function returns an array of
AdministrationClientOrg objects. One of these will be the default organisation (and
has the default flag set) and the rest will be client organisations.
An example jsp is provided that shows how to manage client organisations using the
Yellowfin Java Web Services API. This is located in the
Yellowfin\development\examples\webservices\ folder.
In addition, the clientReferenceId parameter has been added to the
AdministrationServiceClient:
getClientReferenceId()
setClientReferenceId(String)
This is used to identify the client when making certain web service calls. The calls that
are affected by the clientReferenceId parameter are:
loginUser(AdministrationPerson)
logs the user in to the
client organisation
specified by the
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
70
clientReferenceId
parameter
listReportsForUser(AdministrationPerson)
shows reports that the
user has access to at the
client organisation
listGroups()
only operates on groups
getGroup(AdministrationGroup)
belonging to the client
createGroup(AdministrationGroup)
organisation
deleteGroup(AdministrationGroup)
modifyGroup(AdministrationGroup)
addBirtReport(AdministrationReport)
creates the report at the
client organisation
Similarly, in the ReportServiceClient there is a clientReferenceId. There is only one
affected function:
LoadReport(String)
will only load a report that is visible at the client
organisation
When making web service calls, it is important to make sure the clientReferenceId is
set correctly, or it may return unexpected results. For example, to load a report that
belongs to a client organisation, the clientReferenceId in the ReportServiceClient
must be set before calling LoadReport().
SOAP
The SOAP request and response schemas are defined in the Administration Guide.
The additions to these schemas are as follows:
Administration Service Request Schema
Request Element
Data Type
Description
client
Object
AdministrationClientOrg object (see below).
orgRef
String
The client Reference Id used to identify a client
organisation.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
71
Administration Service Response Schema
Request Element
Data Type
Description
people
Array
Array of AdministrationPerson objects
client
Object
AdministrationClientOrg object
clients
Array
Array of AdministrationClientOrg objects
AdministrationClientOrg Schema
Administration
Data Type
Description
clientName
String
The name of the client
clientReferenceId
String
The unique Reference Id used to identify this client
timeZoneCode
String
The local timezone code for this organisation
defaultOrg
boolean
A flag set to true if this AdministrationClientOrg object
ClientOrgElement
represents the default organisation, otherwise set to
false.
LISTCLIENTS
Returns a list of organisations, including the default organisation and any client
organisations.
Note: if the Client Organisations configuration parameter has not been turned on, no
clients will be returned.
Request Parameters
Response
loginId
clients
password
statusCode
orgId
function = “LISTCLIENTS”
GETCLIENT
Returns a client organisation object, based on the passed object.
Request Parameters
Response
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
72
loginId
client
password
statusCode
orgId
function = “GETCLIENT”
client (requires either defaultOrg =
true, or clientReferenceId set)
CREATECLIENT
Creates a new client organisation. The name and reference id must be specified, and
the reference id must be unique. Note that the defaultOrg flag is ignored on the client
(a new default organisation cannot be created).
Request Parameters
Response
loginId
statusCode
password
orgId
function = “CREATECLIENT”
client (requires clientName and
clientReferenceId set)
DELETECLIENT
Deletes a client organisation. Users will no longer be able to log in to this client, and
any content created will not be accessible. If the client object represents the default
organisation (defaultOrg flag is true) the organisation will not be deleted (the default
organisation cannot be deleted).
Request Parameters
Response
loginId
statusCode
password
orgId
function = “DELETECLIENT”
client (requires clientReferenceId
set)
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
73
UPDATECLIENT
Updates a client organisation. If the organisation is the default organisation, the
Name, Reference Id and Timezone code can be updated. If not, only the Name and
Timezone code can be updated.
Request Parameters
Response
loginId
statusCode
password
orgId
function = “UPDATECLIENT”
client (requires either defaultOrg =
true, or clientReferenceId set)
LISTUSERSATCLIENT
Retrieves a list of users that can log in to a client organisation.
Request Parameters
Response
loginId
people
password
statusCode
orgId
function = “LISTUSERSATCLIENT”
client (requires either defaultOrg =
true, or clientReferenceId set)
GETUSERACCESS
Retrieves a list of clients that a user has access to log in to.
Request Parameters
Response
loginId
clients
password
statusCode
orgId
function = “GETUSERACCESS”
person (requires userId set)
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
74
ADDUSERACCESS
Grants access for a user to log in to a client organisation.
Request Parameters
Response
loginId
statusCode
password
orgId
function = “ADDUSERACCESS”
person (requires userId set)
client (requires either defaultOrg =
true, or clientReferenceId set)
REMOVEUSERACCESS
Revokes access for a user to log in to a client organisation.
Request Parameters
Response
loginId
statusCode
password
orgId
function =
“REMOVEUSERACCESS”
person (requires userId set)
client (requires either defaultOrg =
true, or clientReferenceId set)
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
75
The orgRef request parameter must be set to the correct client Reference Id for
the following functions:
LOGINUSER
Logs a user in to a client organisation.
GETUSERREPORTS
Returns a list of reports that a user has access to at a
client organisation.
LISTGROUPS
Returns a list of groups available at a client organisation.
GETGROUP
Returns a group belonging to a client organisation.
CREATEGROUP
Creates a group at a client organisation.
DELETEGROUP
Deletes a group from a client organisation.
MODIFYGROUP
Updates a group at a client organisation.
LOADBIRTREPORT
Creates a BIRT report record at a client organisation.
The only change to the Report Service schema is that
the orgRef request parameter must be set to the correct
client Reference Id for the following function:
SCHEMA
Loads a report definition from the specified client
organisation.
Client Access Filter
The Client Reference Id can be used as an access filter in the same way that a
standard Source Filter is used. When a view is set up, select the field that
corresponds to the Client Reference Id, and go to the Access tab. Change the Access
Filter value to “Client Reference Id”. Save and activate the view. Create a report and
set the Access Filter to be the field selected. The report data will now be filtered
based on the client the user is currently logged in to. If the user logs out, then logs in
to a different organisation, they will see different data based on the new organisation.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
76
Appendix B – Client Orgs Further Information
Data Sources
Sources belong to the organisation they were created at. Users with appropriate
access can see data sources belonging to their “current” organisation (the
organisation they logged in to) or the default organisation.
Source Access Filters
Access Filters are used to restrict users of Yellowfin from accessing specific data in
the application when either running or building a report. For example a manager may
only be allowed to see employee details from his or her own department.
Access Filters match users within Yellowfin to an arbitrary Reference Id such as cost
centre or employee id in the application. The Reference Id for the user can then be
used as a filter when they run reports. For full details of how to implement source
filters please refer to the Yellowfin administration guide.
Views
Views belong to the organisation that owns the data source. A user logged in to a
client organisation can see data sources belonging to the default organisation and
can create views against them. In this situation the views then belong to the primary
organisation, and will be visible to other clients as well. If this is not desired, do not
give users logging in to the client organisation access to create views.
Report Categories
Each organisation has separate report categories. In the Administration – Categories
section, users can see and edit the categories belonging to their current organisation.
Users logged in to a client can still see reports in categories that belong to the default
organisation (unless the categories are restricted). Reports can only be published into
categories that are owned by the current organisation – so they must be created at
each client that will be writing reports.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
77
Reports
Reports belong to the organisation they were created at. Users logged in to the
default organisation can only see reports from that organisation, but users logged in
to client organisations can see and run reports belonging to that client or the default
organisation. Users can only ever edit reports belonging to the organisation they
logged in to.
Dashboards
Corporate dashboard tabs are owned by the organisation they were created at. Users
logged in to a client organisation can access corporate tabs created at that client or
the default organisation. Personal dashboard tabs are available at all organisations
that a user can log in to, but will only contain reports that are visible at that
organisation. Reports that are visible on a dashboard are those from the current client
or default organisation.
Groups
Groups are owned by the organisation they were created at. Users can only see
groups owned by the current organisation they are logged in to.
Roles
Roles are defined at the default organisation only. A user only ever has a single role,
which applies to all client organisations they are allowed to log in to.
User Management
The user management section shows users that can log in to the current
organisation. If a new user is created, they are given access to log in to the current
organisation. If a user is deleted, they will no longer be able to log in to the current
organisation, but they will retain access to any other client organisations that they are
allowed to log in to.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
78
Person Search
Person searches return users that can log in to the current organisations. This
ensures that a user from one client organisation will not be able to see users from
another client organisation.
Web Services
Once the client organisations functionality has been enabled on the Configuration
page, management of client organisations is done via web services. This can be done
with the Yellowfin Java Web Services API, or by making direct web service calls via
SOAP.
Copyright © Yellowfin International pty ltd 2010
www.yellowfin.com.au
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement