Transcript eB.Data namespace - Bentley Communities

© 2010 Bentley Systems, Incorporated
www.bentley.com
eB SDK Training
• Non- API integration
• External Tools for eB Director
• Database events triggering stored procedures
• API-based methods:
• Stand-alone Applications
• Stand-alone Web Pages
• Plug-in Web Pages for eB Web
• Scripts running in Office Apps
• Web Services integration
2 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Integration Methods
3 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Register tools for eB Director
4 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
External Tool operation
5 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Database events
• Core API
– Lets you build your own eB-aware
applications
• Web API
– Lets you access eB objects from
your own web pages
• Web plug-in API
– Lets you add functionality to eB Web
• Web Services API
– Lets you integrate with foreign systems
6 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Structure of the API
• eB.Service.Proxy.dll
– eB.Service.Client namespace – implements the Proxy class
– eB.Data namespace – implements object classes
• eB.Common.dll
– eB.Common.Enum namespace – enumerated types used by
other classes
• eB.Library.Web.dll
– eB.Library.Web namespaces
• eB.Web.Data.dll
– eB.Web.Core namespaces
– eB.Web.UI namespaces
– eB.Web.Data namespaces
7 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
DLLs and Namespaces
Core API
8 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
• Proxy – master class that governs
interactions with all eB objects
• Handles connection, logon, logoff
• Creates, modifies, & deletes objects
• Gets information for an object
• Provides transactions & rollback
9 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Proxy class
• Classes for every object
• Many helper classes
• Used for read operations
• Object-oriented layer on Proxy class
10 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
eB.Data namespace
• Applies meaningful names to lists of values
• eB.Common.Enum.ObjectType
– Lists the names of all eB object types
– 1 = Item 2 = VitualItem 3 = Document
• eB.Common.Enum.GetObject
– Options for flags used when getting object info
• eB.Common.Enum.HasFlags
– Tests whether an object has a given
relationship
11 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Named constants in eB.Common.Enum
© 2010 Bentley Systems, Incorporated
Connecting to the database
12 | WWW.BENTLEY.COM
• Connect using eB.Service.Proxy (old way)
OR
• Connect using eB.Data.Session (new way)
• Expensive operation
– Preserve the connection while user is logged on
13 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Connecting to eB
• Create the Proxy object
myProxy = new Proxy();
• Connect to the Application server
int rtn = myProxy.connect(0, serverName);
• Logon
int rtn = myProxy.logon(0, dataSource, user, pswd);
14 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Initializing eBProxy
int rtn = myProxy.connect ( 0, serverName );
Read vs Write access
0 = Proxy.services.both = read/write
1 = Proxy.services.olap = read
2 = Proxy.services.oltp = write
Use enumerated values for clarity
15 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Read vs Write access
• Get Data Sources from proxy
String dataSources =
myProxy.get_data_sources(0, ref rtnCode);
dataSources string:
16 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Data Source discovery
• Represents context for a logged-on user
• Required for most methods in eB.Data
• Contains active and default scopes
17 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
eB Sessions
• Create the session
eB.Data.Session mySession = new eB.Data.Session()
• Connect to the server
mySession.Connect(SessionTypes.Both, serverName)
• Log on to the application server
mySession.Logon(SessionTypes.Both, community,
username, password)
18 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Initializing a Session
eBProxy
Session
ProtoProxy
19 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Converting from eBProxy to Session
• Log on as Proxy
eBProxy.connect(0, “serverName”);
eBProxy.logon(0, dataSource, userName, pwd);
• Convert to Session
eB.Data.Session session = new eB.Data.Session();
Session.AttachProtoProxy(eBProxy.proto_proxy,
eBProxy.connect_info);
20 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Code for eBProxy to Session
• Logoff-If you don’t logoff and instead just terminate the program, then
the license that was being used by the logged-on user is “quarantined” and
isn’t freed up for reuse for about 20 minutes. By logging off, you free up that
license immediately.
• Disconnect-If you don’t Disconnect, I’m not sure what this does. It
probably just holds onto some Application server resources until timeout is
reached and they are freed up.
• Dispose-. It’s the memory clean-up call. In eB, the dispose method
also logs the user off and disconnects as well.
21 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Cleanup
• Creating objects
int rtnCode = myProxy.add_keyword(keywordName)
• Creating object links
int rtnCode = myProxy.add_document_location( docId, locationId)
• Retrieving object information
string fileInfo = myProxy.get_doc_files_list (docId,
levels, criteria, ref rtnCode)
• Changing objects
int rtnCode = myProxy.chg_location( locationId,
newDesc, newLocationTypeId )
22 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Sample Proxy calls
int rtnCode = myProxy.someMethod (param1, param2)
Updating, deleting, linking an object
success = 1
error < 0
Creating an object
success = object ID
error < 0
23 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Error Handling in Proxy calls
Retrieving object information
success = 1
error < 0
string info = myProxy.someMethod (param1, param2, ref rtnCode)
Return string contains xml data
24 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Error Handling in Proxy calls (cont)
• myProxy.get_error(rtnCode)
25 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Getting the error string
myProxy.silent_mode = true;
• Normally false. Error message pops up.
• If true, trap the message yourself.
• Must be true in web apps or
the web server will hang.
26 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Silent Mode for errors
• Use Exception handling to deal with errors
27 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Error Handling in eB.Data classes
© 2010 Bentley Systems, Incorporated
Getting object information
28 | WWW.BENTLEY.COM
• Old Method
– proxy.get_report – returns multiple objects
– proxy.get_object – returns info on one object
• New Method using eB.Data namespace
– eB.Data.Search – returns multiple objects
– eB.Data.class.Retrieve – returns info on one object
29 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Two approaches to retrieval
• Proxy.get_report()
– Gets all objects meeting specified criteria
• Proxy.get_object()
– Gets all specified data for a single object
33 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Getting object data with eB Proxy
© 2010 Bentley Systems, Incorporated
Using get_report
string xmlStr = proxy.get_report (
string report_name,
string criteria,
string options,
ref int result)
Returns XML string with info
34 | WWW.BENTLEY.COM
Object type to search for
Use rules in next slide to build up a query
Use a blank string or “IDS_ONLY”
Returns 1 for success
columnName operator value AND/OR columnName operator value ...
These booleans are allowed:
- AND
- OR
- AND NOT
- OR NOT
You supply the value
Operators are:
-
like
= (equals)
<> (not equals)
<= (less than or equal to)
>= (greater than or equal to)
Get allowed column names for each
object from get_report_syntax
35 | WWW.BENTLEY.COM
Column names
documented at
get_report_syntax
© 2010 Bentley Systems, Incorporated
Rules for criteria in get_report
(char_str_value.<AttrName> = 'finalized')
Value to search for
Name of the attribute in
angle brackets - Required
Column name for a string attribute value
Use parentheses to avoid ambiguity
36 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Syntax for custom attribute values
© 2010 Bentley Systems, Incorporated
Using get_object
• Gets only one object per call
string xmlStr proxy.get_object (
int pl_object_id,
Internal ID of the object you want
int pl_object_type,
Use eB.Common.Enum.ObjectType
long pl_options,
Bitwise union of options from
eB.Common.Enum.GetObject
ref int pl_result)
Returns all requested data for just one object
37 | WWW.BENTLEY.COM
• Use bitwise OR operator to set options
long options = (long) GetObject.DocumentOptions.Projects |
GetObject.DocumentOptions.Characteristics|
GetObject.DocumentOptions.Locations |
GetObject.DocumentOptions.Security;
long options = (long) GetObject.DocumentOptions.Detail;
long options = GetObject.GetAllObjectOptions (objType, true, true);
38 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Sample options for get_object
• Details option includes a
has_flags element
• Convert content to long and test the
relationship of interest (bitwise AND)
• If 0, no relationship
if (hasFlags & GetObject.DocumentOptions.Projects == 0)
39 | WWW.BENTLEY.COM
No Project links
© 2010 Bentley Systems, Incorporated
Checking for relationships: hasFlags
• eB.Data.Search()
– Gets all objects meeting specified criteria
– One object type per search
• eB.Data.<classes>.Retrieve
– Retrieve method gets specified data
for a single object
– Class used corresponds to the type of object
40 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Getting object data with eB.Data
• Create the search string (as eQL)
String eqlStr = @“START WITH Document
SELECT Id, Code, Name
WHERE Class.Code = ‘DWG’ ”;
• Create the search object
eB.Data.Search srch = new eB.Data.Search( session, eqlStr);
• Run the search
System.Data.DataTable dt = srch.Retrieve<System.Data.DataTable>();
41 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Creating a search for objects
Primary
Object
Columns
to return
Filter Criteria
Sorting
42 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Basics of eQL
Keywords in
upper case
Commas between columns
No comma at end of SELECT
Single quotes
for text
Dot notation
for related
properties
43 | WWW.BENTLEY.COM
Extra spaces
& line breaks OK
© 2010 Bentley Systems, Incorporated
eQL syntax
44 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Generate a list of searchable properties
• eB.Data.SystemData class
• Used for eB configuration information
–
–
–
–
–
–
–
Job types
Keywords
Available Templates
Responsibility Types
Revision rules
Static Lookups
Many others
• SystemData.Retrieve(“prop1;prop2;prop3”)
retrieves specified properties
45 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Getting System Data
• Create the object, using the object ID
eB.Data.Document doc = new eB.Data.Document(session, id);
• Populate the object properties using Retrieve
doc.Retrieve(“Header;Attributes;Files;Securities”);
String docName = doc.Name;
String docCode = doc.Code;
Caution: properties are NULL until retrieved
46 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Using Retreive for object data
• Objects know their own retrieval options
47 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Available retrieval options
48 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Test Retrieval tool
• To add a copy to a document:
– add_doc_copy
• To add a file to a copy:
– add_object_file
• To delete a copy object:
– del_doc_copy
49 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Document, Copy, File API calls
• To get the file ids of all files in all doc copies:
–
get_doc_files_list
• To get the file (as a stream) knowing the file id:
– get_doc_file (file_id, ref stream)
• To delete a file from the repository:
–
del_doc_file (file_id)
• To move a file from one doc copy to another:
–
–
50 | WWW.BENTLEY.COM
del_doc_copy_file
add_doc_copy_file
© 2010 Bentley Systems, Incorporated
Document, Copy, File API calls (cont)
• When updating a document, you must supply
values for all parameters in the method.
• You can supply “no op” values for parameters
you don’t want to change:
– Text:
"%"
– Numeric: -1
– Date:
"02-JAN-1753"
proxy.chg_document (docID, newPrefix, newMiddle, newRevision, newClassID, newTitle);
proxy.chg_document (docID, “%", “%", "ver2.0", -1, “%");
51 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Updating documents
• In the API: Attributes == Characteristics
• First get the ID of the object
str = proxy.get_report ("documents", “title = ‘mydoc’,
“IDS_ONLY”, ref result);
• Then get the IDs of its characteristics
flag = (long) GetObject.DocumentOptions.Characteristics;
str = proxy.get_object (docID, flag, ref result);
• Then update
result = proxy.chg_char_data (docID, charID, value);
52 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Updating document attributes
• Templates aid new object creation
• Provide default settings for
common properties
• Ensure object security gets applied
• Set up links to Projects, Organizations
53 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
About Templates
• Use get_object, not get_report for template list
– Use object ID = 0
• GetObject.TemplateOptions
– NewFromTemplate – All templates with
“Can Use” privilege
– TemplateDocuments – All document templates
with “View” privilege
int objType = (int)ObjectType.Templates;
long options = (long)GetObject.TemplateOptions.TemplateDocuments;
string xmlRes = eBProxy.get_object( 0, objType, options, ref iRes );
54 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Listing Templates
• Part template, part document
(or other target object)
• Two IDs in XML
– <obj_id> in template table
– <object_id> in target object table
• Use objID to get template properties
• Use objectID to get target object
properties
55 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Templates are two-part objects
• Use proxy.add_template
– Takes several parameters to set template
properties
– Returns the template id
56 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Creating templates
• Use proxy.create_from_template(objID)
– Takes the template id as a parameter
– Returns the new document id
57 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Creating documents from templates
Scripting in eB
58 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Hello World!
• Write macros with “code behind” in Excel
• Use any of the eB API calls
• Reference spreadsheet cells to get data
• Combine eB calls with spreadsheet entries
– Create objects
– Modify objects
– Delete objects
59 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Office Application scripting
© 2010 Bentley Systems, Incorporated
Adjustments for VBA
• VB is not managed code
• Register proxy as a COM dll:
> cd C:\Windows\Microsoft.NET\Framework\v2.0.50727
> regasm "path\to\eB.service.Proxy.dll"
• Create the proxy:
Set myProxy = CreateObject("eB.Service.Proxy")
• No overloaded methods in COM
set_object_status
set_object_status_2
set_object_status_3
60 | WWW.BENTLEY.COM
Spreadsheet
Code Behind
61 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Sample spreadsheet
© 2010 Bentley Systems, Incorporated
Event Handlers & Engines
62 | WWW.BENTLEY.COM
• Event is something that happens based on activity in eB
– Approval of an object
– Completion of a work task
– File check-in
• Not database triggers
63 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Event Handlers
© 2010 Bentley Systems, Incorporated
Working with virtual items
64 | WWW.BENTLEY.COM
• A non-tangible aspect of your business
• Part of a:
– Process
– Set of Requirements
– Function, etc
• Can be grouped into hierarchies
• Hierarchy represents the complete
function or process
65 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
What is a Virtual Item?
Virtual Item Group
Nested Virtual Item Group
Virtual Item
Nested Virtual Item
66 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Sample Virtual Item hierarchy
Virtual Item Group
A
Virtual Item Group
B
Grouped VI
Grouped VI
Ungrouped VI
ObjTyp = 123
• Code
• Desc
• Attrs 1
• Links 1
ObjTyp = 123
ObjTyp = 2
add_vitem_grp_member
67 | WWW.BENTLEY.COM
• Code
• Desc
add_vitem
• Code
• Desc
• Attrs 2
• Links 2
add_vitem_grp_member
© 2010 Bentley Systems, Incorporated
Virtual Items & VI Groups
• Virtual Item
add_vitem (code, description)
• Virtual Item Group
– It’s really a document
– Acts as a container for virtual items
add_document (prefix, middle, revNo, classID, title)
Can be an
empty string
68 | WWW.BENTLEY.COM
Class must be of type
Virtual Item Structure or
Virtual Item Baseline
(see subsequent slides)
© 2010 Bentley Systems, Incorporated
Creating Virtual Items & VI Groups
xml = proxy.get_object (objID, objType, options, ref result);
GetObject.ClassGroupOptions.Children
ObjectType.ClassGroups (=184)
objID = 1
Call get_object multiple times for nested classes
xml = proxy.get_object (classID, objType, options, ref result);
GetObject.ClassObject.Children
ObjectType.ClassObject
Get from xml string in previous call
69 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Getting class IDs for creating VI Groups
In the return xml string from get_object, examine <sys_type> in <child>
Look for V or W
70 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Document class for VI Group
• Add VI to group
gvi_id = proxy.add_vitem_grp_member (group_id, vitem_id);
ID for new grouped virtual item
ID of the VI group
ID of the ungrouped virtual item
• Attach grouped VI to VI parent
proxy.add_gvitem_structure(parent_id, child_id);
71 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Adding Virtual Item members
• Use get_object with appropriate options
ObjectType.VirtualItem
xml = proxy.get_object (objID, objType, options, ref result);
GetObject.VitemOptions.GroupsRelated
Examine xml for VI Group info
72 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Getting VI Groups for a Virtual Item
Using workflow
73 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
• A Work Order class and a template
• Work Tasks—the individual steps of the
workflow
• Skills—determine which users may work
on a task
74 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Workflow components
• Create WO from template
• Fill in fields & create links unique to this WO
• Calculate due dates
• Add objects to a work order or a work task
– Adding to work order makes object
visible across the workflow
– Adding to work task limits object to that task
– Make the object subject or reference
• Approve WO to get it started
75 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Life cycle of a work order
• get_object
– Gets the workflow templates
• create_from_template
– Creates the work order
• add_work_order_doc
– Links a document to the work order
• add_work_step_doc
– Links a document to a task on the work order
• calc_wo_schedule
– Calculates from a date based on task durations
76 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
WO calls
• add_template – adds a template to a work
order class
• get_report – gets the list of skills for
assigning to tasks
• add_work_step – adds a task to a work
order template
• add_ws_structure – adds arrow from one
task to another
77 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Developing the work order template
• work_accept – assigns the work task
• work_choose_path – chooses the path in a
branching work order
• work_delegate – delegates a task to a person
or skill group
• work_cancel – cancels specified task in workflow
• work_suspend – stops the work order
• work_resume – restarts the work order
• work_complete – completes the work task
78 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Processing work tasks
Web framework
79 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
• eB Web API
Classes to let you connect
existing web sites to eB
using ASP.NET
• eB Web Plug-in Framework
Classes to let you customize
your eB web environment
80 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Web API Overview
eB Web API
81 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
• Technology for quickly creating websites
• Web pages are built on-the-fly at the server
• Simple tags specify complex UI
– Server builds the complex UI
based on the simple tag
• A web page is divided into two files
– Xhtml page markup
– Code-behind file
– Application logic separate from presentation
82 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
ASP.NET Review
default.aspx
83 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
ASP.NET Review (cont)
default.aspx.cs
• AssemblyInfo.cs – attributes of the assembly
compiled by the ASP.NET project
• Global.asax – “page” containing application
class of the web project
• Web.config – xml file containing settings and
config for the web project
• default.aspx – default web page for the project
84 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
ASP.NET project files
Plug-in Framework
Page classes for eB pages
Plug-in UI controls
Web Core classes
Data structures
Web UI controls v15
85 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
eB Web Library
• eB.Web.eBContext
–
–
–
–
Log on and save state
Maintains Session information
Subsequent pages can use the saved state
Use in place of ProxyWrapper
(if updating v14 code)
eBContext eBcxt = new eBContext(
appServer, dataSource,
userName, password);
eBcxt.SaveInSession(HttpContext.Current);
86 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Maintaining Logon State
• ActivityPage
– ActivityContext provides objects passed to page
– ActivityContext.FocusObject is first eBObject
• AuthenticatedPage
– Derived from ActivityPage
– Uses state saved by eBContext
• ObjectSpecificPage
– Derived from AuthenticatedPage
– Meant to display data for one object per page
– Get object details from ActivityContext
87 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
eB Page classes
• Object Type:
ActivityContext.FocusObject.Id.OfType
ActivityContext.FocusObject.Id.TypeID
• Object Id:
if (!ActivityContext.FocusObject.RetrievedOptions.Contains(“Header”)
{ ActivityContext.FocusObject.Retrieve(“Header”);}
• The object itself:
eBObjectIdentifier eBIdent = ActivityContext.FocusObject.Id.Id;
eB.Data.Document doc;
doc = ActivityContext.Dispenser.Dispense<eB.Data.Document>(eBIdent);
89 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Getting object information on a page
• Mechanism for referencing eB objects via URL
• Opens the object in eB Web
• Syntax to programatically generate URLs
• Send to recipients to point to specific objects
• Remember to URL encode unsafe characters
http://srv1/eb/Search/QuickLink.aspx?u=ADMIN&p=admin&d=training&n=DOC01&t=3
90 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
QuickLinks
• Base URL:
http://<server>/<webapp>/Search/QuickLink.aspx
• Object-specific parameters
–
–
–
–
–
–
n=<prefix>
t=<objecttype>
r=<revision>
m=v or m=l (documents only)
u=<username>&p=<password>&d=<dsn>
s=<connect_info>
http://srv1/eb/Search/QuickLink.aspx?u=ADMIN&p=admin&d=training&n=DOC01&t=3
91 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
QuickLink syntax
© 2010 Bentley Systems, Incorporated
eB Web plug-in framework
92 | WWW.BENTLEY.COM
Plug-ins from Bentley
93 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Bentley uses plug-in architecture
• The Manage eB Web Applications tool lets you
set up multiple web apps connecting to eB
• Each web application at a web site is a unique
combination of plug-ins
– Reviewers: Core, Document Manager, Viewer,
Workflow
– Document Specialists: add Change Management,
SharePoint
– Engineers: add Item Manager, Virtual Item Manager
• Each group accesses eB using a different URL
94 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Managing plug-ins
95 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Manage eB Web Apps utility
Add Custom Object Pages
Add Navigators
Add Searches
Add Basket Tasks
96 | WWW.BENTLEY.COM
Change field format
Add Tasks
© 2010 Bentley Systems, Incorporated
Custom plug-in integration points
• Use sample plug-in projects as templates
• Features of plug-in projects
–
–
–
–
–
97 | WWW.BENTLEY.COM
Object-specific page
Tree control page
Action page
Authenticated web control
Layout control provider
© 2010 Bentley Systems, Incorporated
Visual Studio setup for plug-ins
• Provides minimum requirements for a plug-in
• Implement these methods in PlugIn.cs:
– FormPath – determines which objects the plug-in will
handle & identifies the redirect pages
– TaskList – adds tasks to Task panel for specified
objects
• The class also reads config files to add
navigators, search UI, and other UI elements
– AppElements.config
– PlugIn.config (removed in 15.4)
98 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
ConfiguredPlugIn class
• Unique ID for every plug-in
• Plug-in ID must match Installation folder
• Plug-in class and dll names
should reflect function
Plug-in ID
99 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Plug-in naming
• Copy .dll to bin folder in virtual directory
• Include .pdb if debugging is required
• Add subfolder to PlugIn folder in virtual directory
– Subfolder name = plugin ID
– Copy PlugIn.Config, .aspx, .ascx, css, etc from
project.
• Edit web.config
– Add entry in <FrameworkSettings><PlugIns>
element
100 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Deploying eB Web plug-ins
• Can’t debug in isolation
• Deploy project files to plug in folder
• Copy dll and pdb to web app bin directory
• Start browser, navigate to website
• In Visual Studio, Attach to Process
– w3wp.exe for IIS
101 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Debugging a plug-in
• Add a page to your project
– Use Page class derived from ObjectSpecificPage
– Page uses ObjectDisplay.Master
with content placeholders
• Add controls to your page
– CustomisableDisplayContainer
• Modify FormPath to redirect to your new page
• Competition for object display – Winner Takes All
– [assembly: eB.Library.Web.PlugIn.Attributes.PlugInPriority(110)]
102 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Adding object display pages
CustomisableDisplayContainer
CustomisablePropertiesContainer
CustomisableRelationshipsContainer
These controls respect Layout Editor changes
103 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Object display controls
View or Edit mode
Contains info about the
item to be displayed
Check for retrieval
Examine object data
Redirect string
Lets other plug-ins
handle the object
104 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
FormPath method in PlugIn.cs
• Get metadata for an eB object from TargetObject
– Check for eB object: TargetObject.IseBObject()
– TargetObject.Activity.FocusObject.Retrieve(“Header”)
• After retrieval, create the eB.Data object
– if (targetObj.eBId.OfType = ObjectType.Document)
{
eB.Data.Document doc =
targetObj.Activity.FocusObject.Inner)
}
105 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
TargetObject
• TaskList method in PlugIn.cs adds an
action to the Task Panel
• CategorizedTaskList object stores the
collection of tasks for an eB object
• Use the AddTask method
106 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Adding Tasks to Task Panel
Contains info about the
item to be displayed
List of tasks
task id
category title
task name
uri to image
uri to task page
target window
107 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
AddTask method in PlugIn.cs
• Use PlugIn.Config file, <BasketAction> tag
• Creates an object of type PageTask
108 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Adding Tasks to Basket
• Framework provides controls
for known data types
• Customize layout with LayoutControlProvider
• Four methods to implement:
–
–
–
–
109 | WWW.BENTLEY.COM
PropertyControl – Displays properties and attributes
PropertyControlValue – Updates properties
RelationshipControl – Displays relationship table
ColumnControl – Displays a column in relationship
table
© 2010 Bentley Systems, Incorporated
Changing field format
• Technique:
– Use Layout Editor to create new data type for a property
– In your project, derive from LayoutControlProvider class
– Implement PropertyControl method (for example)
• Examine supplied property for relevant
characteristics (e.g. new data type)
• Create new control
• Return control
– Framework hooks up control to page and property
– Register LayoutControlProvider class in PlugIn.config
110 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Changing field format (cont)
• Add entries to the list of Navigators
• Navigator types:
– Tree control
– Other web controls
• Register navigators in AppElements.config
111 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Custom Navigators
• TreeNavigationProvider
Builds a tree control and displays one or
more root objects, and selected children
• WebControlNavigationProvider
References a web control, in which you
can display any actions or links you want
112 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Custom Navigators (cont)
• Entry in AppElements.config creates a TreeControl
• References .aspx page describing the tree content
Page describing
tree content
113 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
TreeNavigationProvider
• Use TreeExploder.aspx page to specify contents
• Contents are combinations of these controls:
–
–
–
–
–
–
–
114 | WWW.BENTLEY.COM
TreeExplode – get_explode on the root object
TreeSearch – get_report on the root object
TreeQuery – sql query on the root object
TreeGroup – arbitrary container for other objects
TreeLink – a leaf node that links to another page
TemplatesNode – shows templates for a class
ExplodeAddObjectTrees – expands the object and
adds subtrees for child objects
© 2010 Bentley Systems, Incorporated
Content for TreeControl
115 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
TreeControl example
• AppElements.config entry adds to the list of Navigators
• Displays a web control of your choosing
– Specified by the ASCX property
– Often used to display a list of commands or links to other pages
116 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
WebControlNavigationProvider
• Your searches appear in the Search drop-down list
• Register searches in AppElements.config
• Design the search fields in the .ascx page
117 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Custom Search
• Create .ascx page
• Use SearchParametersControl class
• Class handles submitting the search
to eB (using proxy.get_report)
• Use BuildQuery method to add criteria
to queryData search structure
• Provide your own UI for this control
118 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Designing the Search control
• System Menu Task – Adds top-level icons
• Preferences – Adds user options to the
preferences page
• Object Creation – References pages to
create new objects
• Pickers – Specify classes of pickers for
choosing objects
119 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Additional PlugIn.config entries
• Sampling of UI controls for eB pages
–
–
–
–
–
–
120 | WWW.BENTLEY.COM
CustomizableDisplayContainer – Layout Editor sensitive
DateControl – Pick dates by calendar
FileUploadControl – Drag & drop target for adding files
LogInControl – Displays log-in screen
LayoutPanelManager – Lists sections from Layout Editor
LayoutSectionsList – Drop-down list of Layout Editor
sections
© 2010 Bentley Systems, Incorporated
eB Web UI controls
© 2010 Bentley Systems, Incorporated
Web Services integration
121 | WWW.BENTLEY.COM
• Standard for making Remote Procedure Calls
from client to server
• Uses HTTP POST or SOAP
• Server publishes methods in WSDL file
• Client and Server are loosely-coupled
122 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Web Services fundamentals
http://ServerName/eBSite/WebProxy.asmx
Listings of all
Web Services
methods
123 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
WebProxy.asmx
• No Connect
method, just Logon
• Logon returns
session string
• Use session string
in subsequent calls
• Acts like
proxy.connect_info
124 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Connecting and logging on
125 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
WebProxy Test Page
Using SOAP 1.2
Using HTTP POST
126 | WWW.BENTLEY.COM
© 2010 Bentley Systems, Incorporated
Sample WebProxy call