The following sample illustrates the use of the existing workspace service and will allow developers to better understand the way that K2.net™ 2003 Workspace leverages this web service to retrieve process-related reports from the Log data store.

The following image explains the relationship between the data, report and templates used by the Workspace to retrieve and display the report:

 

Explanation of the Included Example Project


1.  

Open the Reporting Application Sample solution (WorkspaceData.sln located in the zip file) in Visual Studio.NET 2003, the web reference in the solution window points to http://localhost/K2V3/WorkspaceService/FilterService.asmx. Click on the URL to test the web service (Default installation location of K2.net™ 2003 Workspace), if the web service does not load correctly remove the reference and add the reference from the correct location.

Note: The example assumes that the Web Reference Name is ReportService.
 
 
2.Run the sample, make sure that the K2.net™ 2003 Server Service is running. Type in the K2.net™ 2003 Server Name and click on the Button.
  FQN = RptService.CreateSession(txtServer.Text, "")
  The CreateSession method creates a session with the Web Service and return the Fully Qualified Name (FQN), the FQN is used later on to return process data based on the relevant rights of the user stored in the FQN. The User Name textbox is used to store the return parameter in.

3.

The Report Name dropdown lists the standard reports available in K2.net™ 2003 Workspace, select the required report from the dropdown. Based on the selection made in the dropdown complete the required parameters as illustrated in the parameter textbox.

  • The Report Name dropdown lists the standard reports available in K2.net™ 2003 Workspace, select the required report from the dropdown. Based on the selection made in the dropdown complete the required parameters as illustrated in the parameter textbox.
  • Process Overview - UserName:[UserName]
  • ProcessInstance - UserName:[UserName]|ProcName:[Process Name]|Folder:[Folder]
  • ProcessData - UserName:[UserName]|ProcInstID:[Process Instance ID]
  • ActivityInstance - UserName:[UserName]|ProcInstID:[Process Instance ID]
  • Activity Data - UserName:[UserName]|ActInstID:[Activity Instance ID]
  • Events - UserName:[UserName]|ActInstID:[Activity Instance ID]

Note: Refer to the "Reports Filter Parameters" section below for more information.

Note: FQN returned from the CreateSession can be used in all subsequent parameters as the User Name. Replace the values in the square brackets "[UserName]" with the correct values e.g. Process Data - UserName:FQN|ProcInstID:12
4.  Click on the Get Data button to retrieve the report based on the parameters specified in the previous step.
 
Note: Refer to the "Break down of the code sample" section below for more information.

Break down of the code sample

NewUserTemplate (Line 213):
UserName (String)Each user making use of K2.net™ 2003 Workspace have the ability to add, delete and change views within the reports. Changes made by user A will not affect changes made by user B allowing each user to have his own view of K2.net™ 2003 Workspace, the NewUserTemplate insures that the current user have his own set of templates.


GetID (Line 219):
ReportName (String)

The ReportName parameter is required and determines the actual report that will be used later on in the GetData method. The following default report are available within K2.net™ 2003 Workspace: ProcessInstance, ActivityInstances, Events, ProcessData, ActivityDestination, Process Data Audit, Activity Data, Activity Data Audit, Process Instance Audit, Activity Instance Audit, Escalation Data, Process Statistics, Process Statistics Graph, User Performance, User Performance Graph, Process Information, Activity Statistics, Activity Statistics Graph, Process Overview, Processes per Status, User Statistics, User Statistics Graph, Activity Detail
 

TemplateName (String)The Template defines the filters, display columns and sort order that will be used on the report. The Template "All" will always exist as this is the default view of each report.
 
UserName (String)

The CreateSession method creates a session with the Web Service and return the Fully Qualified Name (FQN), the FQN is used later on to return process data based on the relevant rights of the user.



GetData (Line 226):
ReportIDThe report id parameter provides the information about the report used with in the query. The report defines "From" section of the sql query used to retrieve the data.
 
TemplIDThe template id parameter provides the information about the template used with in the query. The template defines "Select, Where and Order" section of the sql query used to retrieve the data.
 
PageID

Used for sub report templates e.g. Each Process Overview Can have multiple process Instance Report Templates, those drill through report templates will be Pages

ParameterStrRefer to the "Reports Filter Parameters" section below for more information.
 
UserName

The CreateSession method creates a session with the Web Service and return. the Fully Qualified Name (FQN), the FQN is used later on to return process data based on the relevant rights of the user.

 

ReportID

The report id parameter provides the information about the report used with in the query. The report defines "From" section of the sql query used to retrieve the data.

TemplID

The template id parameter provides the information about the template used with in the query. The template defines "Select, Where and Order" section of the sql query used to retrieve the data.

PageIDUsed for sub report templates e.g. Each Process Overview Can have multiple process Instance Report Templates, those drill through report templates will be Pages
 
ParameterStrRefer to the "Reports Filter Parameters" section below for more information.
 
UserNameThe CreateSession method creates a session with the Web Service and return the Fully Qualified Name (FQN), the FQN is used later on to return process data based on the relevant rights of the user.
 
SortOrderSpecify the order field used on the dataset.
 
SortDirTwo types of ordering can be used: Asc (Ascending) or Desc (Descending)
 
NumberItemsSpecify the Number of records that can be contained by a page.
 
PageNo

Determine the page that will be returned in the dataset e.g. in total 30 Process instances, NumberItems = 10 and PageNo = 3. The result will return page 3 containing process instances between 20 and 30.

 

ReportIDThe report id parameter provides the information about the report used with in the query. The report defines "From" section of the sql query used to retrieve the data.
 
TemplIDThe template id parameter provides the information about the template used with in the query. The template defines "Select, Where and Order" section of the sql query used to retrieve the data.
 
UserName

The CreateSession method creates a session with the Web Service and return the Fully Qualified Name (FQN), the FQN is used later on to return process data based on the relevant rights of the user.

 

ReportIDThe report id parameter provides the information about the report used with in the query. The report defines "From" section of the sql query used to retrieve the data.
 
TemplIDThe template id parameter provides the information about the template used with in the query. The template defines "Select, Where and Order" section of the sql query used to retrieve the data.
 
ParameterStrRefer to the "Reports Filter Parameters" section below for more information.
 
UserNameThe CreateSession method creates a session with the Web Service and return the Fully Qualified Name (FQN), the FQN is used later on to return process data based on the relevant rights of the user.
 
ReportIDThe report id parameter provides the information about the report used with in the query. The report defines "From" section of the sql query used to retrieve the data.
 
TemplIDThe template id parameter provides the information about the template used with in the query. The template defines "Select, Where and Order" section of the sql query used to retrieve the data.
 
ParameterStr

Refer to the "Reports Filter Parameters" section below for more information.

UserNameThe CreateSession method creates a session with the Web Service and return the Fully Qualified Name (FQN), the FQN is used later on to return process data based on the relevant rights of the user.
 
SortOrderSpecify the order field used on the dataset.
 
SordDirTwo types of ordering can be used: Asc (Ascending) or Desc (Descending)
 
NumberItemsSpecify the Number of records that can be contained by a page.
 
PageNoDetermine the page that will be returned in the dataset e.g. in total 30 Process instances, NumberItems = 10 and PageNo = 3. The result will return page 3 containing process instances between 20 and 30.
 

Note: The GetData method returns a dataset with 3 data tables:

  • ReportData - All records where filtering and return column specification has been applied based on the parameters used in the GetData method.
  • AllData - Returns all columns available for this report.
  • OtherData - Returns ReportName, ReportXML, TemplateName and TemplateXML.

 
Report Filter Parameters
K2.net™ 2003 Workspace comes with 6 predefined reports, the parameter (ParameterStr) will differ slightly depending on the report used in the GetData method. Please refer to the table below for a detailed breakdown on the available options for each report.
Process Overview
RequiredUserName
Optional -
ExampleUserName:FQN
ProcessInstance
RequiredUserName, ProcName, Folder
OptionalProcessInstanceID, Process_Folio, Originator, Status, Priority
Example"UserName:FQN|ProcName:ProcName|Folder:ProjectName|ProcessInstanceID:12|
Process_Folio:MyFolio|Originator:Bob|Status:Active|Priority:1"
Note: The following values are available for Status: Active, Running, Error, and Completed.
The following values are available for Priority: 0 (High), 1 (Medium), 2 (Low)
ActivityInstances
RequiredUserName, ProcInstID
OptionalActivity_Name, Priority, Status, ActInstID
Example"UserName:FQN|ProcInstID:42|Activity_Name:HRApproval|Priority:1|Status:Active|ActInstID:13"
Note: The following values are available for Status: Active, Running, Error, and Completed.
The following values are available for Priority: 0 (High), 1 (Medium), 2 (Low)
Events
RequiredUserName, ProcInstID, ActInstID
OptionalEvent_Name, Destination, Priority, Status
Example"UserName:FQN|ProcInstID:41|ActInstID:78|Activity_Name:HRApproval|Priority:1|Status:Active|
ActInstID:1|ActInstID:23"
Note: The following values are available for Status: Active, Running, Error, and Completed.
The following values are available for Priority: 0 (High), 1 (Medium), 2 (Low)
ProcessData
RequiredUserName
OptionalProcName, ProcInstID, Data_Name, Data_Value
Example"UserName:FQN|ProcName:MyProc|ProcInstID:34|Data_Name:MyDataField|
Data_Value:MyCurrentValue"
ActivityDestination
RequiredUserName
OptionalActDestID , Activity_Name, ActInstID, ProcInstID, Destination, ProcName, ProcFolder
Example"UserName:FQN|ActDestID:2|Activity_Name:HRApproval|ActInstID:12|ProcInstID:23|
Destination:Domain\User|ProcName:ProcessName|ProcFolder:ProjectName"
ProcessDataAudit
RequiredUserName
OptionalAProcess_Name, ProcInstID, Data_Name, Current_Value
Example"UserName:FQN|Process_Name:ProcessName|ProcInstID:23|Data_Name:DataFieldName|
Current_Value:MyCurrentName"
 
Using the Find method
The following section discusses the Find method in detail with relevant example.
SearchXML (XMLNode)XMLDocument determining search details including Scope, Filter and Sorting.

Criteria – The value to search for in the search.
Scope – Indicate which sections should be included in the search.
DateFilter - All dates must be in the following date format: DD MMM YYYY (29 Sept 2004)
ProcessFilter – Limit the search to a specific process.
Sort – Sort values must be in the following format: OrderField1 Asc, OrderField2 Asc
 
UserName (String)The CreateSession method creates a session with the Web Service and return the Fully Qualified Name (FQN), the FQN is used later on to return process data based on the relevant rights of the user.
 
PageNo (Integer)Determine the number of pages to return in the result.

Note: The Find method returns a dataset with 1 data table:

  • SearchData – Returns Record row for data that qualifies according to provided search criteria.
 
Creating a Custom Report
The following section discusses the extensibility of K2.net™ 2003 Workspace by creating and configuring custom reports. Workspace reporting consists of a Report and Template, both defined as a XML Document. Note that the following section refers to files that can be located in the supplied zip file.

Report
•  The Report contains a SQL Query that is formatted into a XML document.


Note: This image illustrates the basic layout of the XML Document. The sections enclosed in square brackets are not valid values and are used only as explanations for the respective sections. See Report_Empty.xml (Included in the zip file)
•  Create a SQL Query that will return the required data from the K2.net™ 2003 Log Database. See SQLQueryScript.sql (Included in zip file).
•  Parse the SQL Query into the XML Document. See Report_Query.xml (Included in zip file).

 
Template
A template is a XML document that determines the available fields, filters and sort order for the report. K2.net™ 2003 Workspace creates a default template for each report the first time a user opens Workspace. When creating new reports you need to specify the template that has to be associated with the report. All the changes made by the user will be updated and saved back to the template, thus allowing users to customize the Workspace to their requirements without affecting other users.



Test the Sample Report
•  Extract the MyCustomReporting sample web application from the zip file to "C:\Inetpub\wwwroot" open Internet Information Services (IIS) Manager.
•  Expand Default Websites and right click on MyCustomReporting folder. Select properties from the menu.
•  Click on the Create button located on the Directory tab. Click on the Directory Security tab and ensure that Anonymous access is disabled on the website.
Note: The sample app assumes that the K2.net™ 2003 Workspace Web Service is located in the default installation location: http://localhost/K2V3/WorkspaceService/FilterService.asmx. Click on the link to test the location of the web service, if the web service does not load correctly reconfigure the web service reference of the sample project in Visual Studio.NET 2003
•  Open InsertNewReport.sql in SQL Query Analyzer (located in the zip file). Execute the query on the K2.net™ 2003 Log database to insert a new report.
  
IDUnique identifier of the report, the ID field is configured as an auto number field and therefore does not require an ID to be specified when a new Report is added to the table.
 
ReportName

Contains the name of the Report, insure that all report names stays unique as it is used in the GetID method discussed in the previous section of the document.

ReportDescrThe description field is optional, and can contain a detailed description of the Report up to 128 characters.
 
ReportXMLContains the XML Document containing the SQL Query discussed in the Report section.
 
TemplateXMLContains the XML Document used to create the default template for the report discussed in the Template section.
 
CustompathSpecify the URL of the page that will display the information for this report. The sample assumes that the custom page URL is: http://localhost/MyCustomReporting/CustomReport.aspx.
 
ViewReportDetermines whether K2.net™ 2003 Workspace will make the report available in the Report List section. 1 – Available or 0 – Unavailable.
 
•  Browse to http://localhost/MyCustomReporting/CustomReport.aspx to test the new report.
•  Open K2.net™ 2003 Workspace, notice that the new report is available under the Report List and can be loaded directly into the existing K2.net™ 2003 Workspace.
   As shown in the image below, the custom report is available from "My Report Example"