Out of the Box Content - Integration Guide. Users, Security, Web Services & Client Organisatio

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>

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

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

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

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

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

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 clientReferenceId parameter

listReportsForUser(AdministrationPerson) shows reports that the user has access to at the

only operates on groups belonging to the client organisation

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 Report Service Request Schema

The web services request should be of the following form:

Request Element Data Type Description

loginId String Username to access Yellowfin

reporting system.

password String Password to for the Username

supplied

orgId Integer The organisation internal Yellowfin Id orgRef String Organisation Identifier if the internal

Yellowfin Id is not known.

reportId Integer Report Id of the report that you want to run.

objectName String Reference Id for reports in a distributed computing environment.

reportRequest String Operation to be performed with this web services request. Options include:

CHART, PDF, HTML, INFO, CSV, RESULTSET

languageCode String Language code for the return response.

Filters Array Array of ReportFilter objects (see below) for passing filter information to the requested report.

URL String URL of Image renderer. Used for

embedding in HTML when charts are attached.

Report Filter Element Data Type Description

filterId Integer FilterId for the user prompt filter which the data applies.

dataValue String Data value to be placed into the user prompt field

Response Schema

The web services response should be of the following form:

Response Element Data Type Description

ReportId Integer Report Identifier of the returned data.

StatusCode String Status of the web services request.

FormatCode String Format code of the report data.

LastRunTime Decimal YYYYMMDDHHMMSS date format of last report run time

ReportType String Report type of requested report LastRunStatus String Success status code of report at last

run.

Report Name String Text description of requested report HitCount Integer Report hit count, including hits from the

web front end.

BinaryData String Base 64 encoded binary chunk of image, HTML, CSV or PDF.

Results Array Array of ReportRow objects (see below) that contain results for each column for a each row in the report result set.

Columns Array Array of ReportSchema objects (see below) that contain information on each column in the data set, and whether the report requires user prompt filter data to be passed to it.

ContentType String MIME ContentType of the returned report object. Possible values include

“text/html”, “text/comma-separated-values”, “image/png”, “application/pdf”

Messages Array Array of Strings that shows debug information as report is run on the server. Used for debugging and tracing errors.

Charts Array Array of ReportChart objects (see below) that contains multiple chart bitmaps when attached to a HTML report response.

Report Chart Element Data Type Description

ReportIndex Integer Index of image in the embedded delivered HTML

ContentType String MIME Content Type of this chart.

Possible values include “image/png”,

“image/jpg”

Data String Base 64 binary image data

Filename String Filename of embedded file in HTML

Report Schema Element

Data Type Description

ColumnName String Column name

DisplayName String Display name of column

DataType String Data type of the column

ColumnLength String Column length

Hidden Boolean Whether the column is displayed on the report or not.

The PDF request returns basic report information and a PDF rendering of the report.

The PDF document is base 64 encoded in the BinaryData field.

Request Requirements Response

LoginId ReportId

Password ReportName

OrgId HitCount

ReportId FormatCode

reportRequest = “PDF” BinaryData ContentType

CSV

The CSV request returns basic report information and a CSV representation of the report table. The CSV document is base 64 encoded in the BinaryData field.

Request Requirements Response

LoginId ReportId

Password ReportName

OrgId HitCount

ReportId FormatCode

reportRequest = “CSV” BinaryData ContentType

HTML

The HTML request returns basic report information and a HTML representation of the report. The HTML document is base 64 encoded in the BinaryData field. If the HTML contains images, such as rendered charts, these will be included in Charts array. Attached charts are base 64 encoded and need to be manually decoded by the client system. The URL request string is used to embed the URL within the HTML for decoding the base 64 images on the client system.

Request Requirements Response

LoginId ReportId

Password ReportName

OrgId HitCount

ReportId FormatCode

reportRequest = “CSV” BinaryData

URL ContentType

Charts

SOAP Administration Service Request Schema

Request Element Data Type Description

loginId String Username to access Yellowfin reporting system password String Password for the Username supplied

orgID Integer The organisation internal Yellowfin ID

orgRef String Organisation identifier if the internal Yellowfin ID is not known

sessionID String SessionID for current webservice session

function String Function to be performed by AdministrationService.

Options include:

ADDUSER, DELUSER, GETUSER, LOGINUSER person Object AdministrationPerson object containing personal data

Administration Person Element

Data Type Description

FirstName String First name of person LastName String Last name of person Initial String Middle initial of person

SalutationCode String Salutation Reference Code. Default values are: DR, MR, MISS, MS, MRS

LanguageCode String Language Reference Code EmailAddress String Email address of person

UserID String UserID used by person to login to Yellowfin Password String Plain text password of person

RoleCode String Role Reference Code

Response Schema

Request Element Data Type Description

SessionID String SessionID of the current webservice session StatusCode String Status of the web services request

LoginSessionID String Key to allow login to Yellowfin via single sign on from a third party application

person Person AdministrationPerson Object containing Personal data Messages Array Array of Strings that shows debug information as the

report is run on the server. Used for debugging and tracing errors

Administration Service Functions Information

To specify the function the web service response returns the function element must be set to one of the following codes.

Info

The INFO request returns basic a status code of “SUCCESS” if the login and password fields have been authenticated by the webservice.

Request Requirements Response

LoginId StatusCode

Password OrgId

Function=”INFO”

GETUSER

The GETUSER request returns information regarding the user specified by the UserId in the person object.

Request Requirements Response

LoginId StatusCode

Password Person

OrgId

Person (requires UserId) Function=”GETUSER”

DELUSER

Delete a user based on the user specified by the UserId in the person object.

Request Requirements Response

LoginId StatusCode

Password OrgId

Person (requires UserId) Function=”DELUSER”

LOGINUSER

Login User specified by the UserId in Person. Also requires the Password to be included. Returns a LoginSessionId. This can be used to login the user directly into Yellowfin, by-passing the login screen. Use the URL:

http://<yellowfin-server>/logon.i4?LoginWebserviceId=<LoginSessionId> to login.

Once the loginSessionId has been used once, you will have to query the web services again for another LoginSessionId.

Request Requirements Response

LoginId StatusCode

Password LoginSessionId

OrgId

Person (requires UserID, Password) Function = “LOGINUSER”

ADDUSER

Add a user into Yellowfin. Will use all details in the Person object to add the user to the Yellowfin database

Request Requirements Response

LoginId StatusCode

Password OrgId

Person (all details required) Function = “ADDUSER”

UPDATEUSER

Update a user in Yellowfin. Will use all details in the Person object to update the user to the Yellowfin database

Request Requirements Response

LoginId StatusCode

Password OrgId

Person (all details required) Function = “UPDATEUSER”

GETUSERREPORTS

Request Requirements Response

LoginId StatusCode

Password OrgId

Person (all details required) Function = “GETUSERREPORTS”

LISTGROUPS

Returns a list of User Groups in Yellowfin. Groups are returned as a list of AdministrationGroup objects.

Request Requirements Response

LoginId StatusCode

Password Groups

OrgId

Function = “LISTGROUPS”

GETGROUP

Returns details about one specified group.

Request Requirements Response

LoginId StatusCode

Password Group

Group (GroupName required) Function = “GETGROUP”

Load an XML BIRT definition into Yellowfin. Will upload the reports and make it active for immediate usage.

Request Requirements Response

LoginId StatusCode

Password Report

Report (with BirtData populated) Function = “LOADBIRTREPORT”

ClientOrg Schema

Administration ClientOrgElement

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

In document Integration Guide. Users, Security, Web Services & Client Organisation Functionality (Page 64-92)