Integration Guide. Users, Security, Web Services & Client Organisation Functionality

(1)

Integration Guide

Users, Security, Web Services & Client Organisation

Functionality

Release 5.1 January 2011

(2)

Yellowfin ® Release 5.1 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.

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

(3)

Info ... 80 GETUSER ... 80 DELUSER ... 81 LOGINUSER ... 81 ADDUSER ... 82 UPDATEUSER ... 82 GETUSERREPORTS ... 82 LISTGROUPS ... 83 GETGROUP ... 83 CREATEGROUP ... 83 MODIFYGROUP ... 83 DELETEGROUP ... 84 LOADBIRTREPORT ... 84 ClientOrg Schema ... 85 LISTCLIENTS ... 85 GETCLIENT ... 85 CREATECLIENT ... 86 DELETECLIENT ... 86 UPDATECLIENT ... 86

(6)

LISTUSERSATCLIENT ... 87 GETUSERACCESS ... 87 ADDUSERACCESS ... 87 REMOVEUSERACCESS ... 88 LOGINUSER ... 89 GETUSERREPORTS ... 89 SCHEMA ... 89

Client Access Filter ... 89

Appendix B – Client Orgs Further Information ... 90

Data Sources ... 90

Source Access Filters ... 90

Views ... 90 Report Categories ... 90 Reports ... 91 Dashboards ... 91 Groups ... 91 Roles ... 91 User Management ... 91 Person Search ... 92 Web Services... 92

(7)

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.

(8)

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.

(9)

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

(10)

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.

(11)

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.

Test Web Service Create User Error Success Successful Successful Failed User Already Exists

(12)

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.

(13)

Test Web Service Get User Error Success Successful Successful Failed User Not Found

Update User Delete User

Failed Failed

Successful

The following code will call the Yellowfin web service to edit a user.

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

(14)

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.

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

(15)

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.

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.

(16)

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.

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.

(17)

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.

Test Web Service Single Sign On Error Log In User Token Successful Successful Failed Failed

(18)

The following code will call the Yellowfin web service to perform Single Sign On.

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.

(19)

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.

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

(20)

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

yftoolbar true/false

Whether or not to show the toolbar (Dashboard, Create Report, Report List and Administration links) on appropriate pages. Setting this option overrides the system-wide configuration setting.

entry dashboard reportlist createreport administration viewreport

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.

reportid ReportId When entry=viewreport, this specifies the report

to view.

reportname Report Object

Name

When entry=viewreport, this specifies the report to view.

disablesourc

efilters true/false

If this is set to true, source filters will be disabled on all reports run by this user during the login session. Only enable this for users who are 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.

hideheader true/false

If this is set to true, the page header will not be shown. Setting this option overrides the system-wide configuration setting.

hidefooter true/false

If this is set to true, the page footer will not be shown. Setting this option overrides the system-wide configuration setting.

(21)

hidesidenav true/false

If this is set to true, the page left navigation will not be shown. Setting this option overrides the system-wide configuration setting.

hidelogoff true/false If this is set to true, the logoff links will not be shown.

reasoncode reason A reason code to include in events logged

during this user's session

reasondescri

ption reason

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.

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

(22)

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:

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

(23)

The following code will call the Yellowfin web service to perform a Logoff with a Session Id specified:

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

(24)

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

(25)

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.

(26)

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

(27)

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.

(28)

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:

The SQL to retrieve each user's relationship to a store would be: User Table UserId UserName FirstName LastName DateOfBirth UserStore Table UserId StoreCode

(29)

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.

(30)

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.

(31)

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.

(32)

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.

(33)

Assigning Users to Groups via the Yellowfin Web service

Test Web Service Get Group Load Members Go Through Checks Call Directly Check If User In Group Include User In Group Success Successful

To include a user in a group execute the following:

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

(34)

To exclude a user from a group execute the following:

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:

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.

(35)

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.

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.

(36)

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.

(37)

The functionality should ideally be replicated in a standalone application or integrated into the OEM application.

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:

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

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.

(38)

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

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

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:

(39)

AdministrationClientOrg client = new AdministrationClientOrg(); 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);

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:

AdministrationServiceResponse rs = null; AdministrationClientOrg[] clientList = null;

rsr.setLoginId(this.username); rsr.setPassword(this.password); rsr.setOrgId(PRIMARYORG);

(40)

rs = AdministrationService.remoteAdministrationCall(rsr); clientList = rs.getClients();

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:

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

(41)

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

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

(42)

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:

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

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.

(43)

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

AdministrationPerson user = new AdministrationPerson(); AdministrationClientOrg client = new

AdministrationClientOrg();

(44)

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); rsr.setClient(client) rs = AdministrationService.remoteAdministrationCall(rsr);

(45)

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.

(46)

Yellowfin runs in central frame, all required links are internal. Top frame S id e F ra m e

Traditional Frames approach.

Portal / Application Links

E xi st in g N a vi g a ti o n

Portal / Application Links Yellowfin runs embedded in page. Better usability and adherence to existing look and feel.

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.

(47)

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:

(48)

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.

Yellowfin Database Yellowfin Database Corporate Directory Corporate Directory Existing Intranet / Portal Yellowfin Application Server Yellowfin Web Services Server Existing / OEM Application Existing / OEM Application Web Services call

Using web services the existing application is delivered report lists and report content through a remote program call.

(49)

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.

(50)

Navigation Replacement & Functionality

Removing or replacing navigation has to be evaluated based upon the user actions within Yellowfin.

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.

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 Header

Use the standard Yellowfin header on every page. This includes the title of the page, and a link to log the user off.

(51)

Custom Header Use a custom header.

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

(52)

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.

(53)

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:

(54)

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

#

(55)

# Yellowfin Database Type - Required

# 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" #

(56)

# Database Port - Not required, will use default for specified DB. #

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

(57)

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/WEB-INF/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.

(58)

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.

(59)

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.

(60)

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 Distinguishing Name

Base DN under which all Yellowfin users and groups are connected.

LDAP Yellowfin User Group

LDAP Group Name of which all users that are allowed to 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 Password

The LDAP Password required for the Yellowfin application to connect to the LDAP.

LDAP Search Attribute

This is unique „user name‟ field that LDAP users will use as their Login into Yellowfin. This is an LDAP parameter such as Email address or Employee Number.

First Name Attribute Name

This maps to the first name attribute of the user within the LDAP directory. This is so Yellowfin can match the user to a name and create an internal user account.

Surname Attribute Name

This maps to the surname attribute of the user within the LDAP directory. This is so Yellowfin can match the user to a name and create an internal user account.

(61)

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.

Integration Guide. Users, Security, Web Services & Client Organisation Functionality