SharePoint Taxonomy ServiceObject

yazooalbumΑσφάλεια

3 Νοε 2013 (πριν από 4 χρόνια και 7 μέρες)

691 εμφανίσεις

SharePoint Taxonomy ServiceObject


Code sample

Introduction

SharePoint 2010 introduces a new feature called Managed Metadata. In short, this allows you to define
groups of terms (term sets) that can take on a range of valid values (terms). These terms
can then be
used in lists and content type columns to allow users to pick from the list of available terms in the term
set. This makes it possible to apply a taxonomy that makes items

easier to categorize and search
. For
an introduction to managed metada
ta, please see this article on
MSDN
.

Unfortunately,
K2 blackpearl 4.5 1370
does not provide explicit

support for managed metadata fields.
There are two basic techniques for reading/upda
ting SharePoint list items: wizard
s

and SmartObjects.
The table below summarizes the operations that can be performed

with various tools
. The
T
erm GUID is
the internal GUID that SharePoint assigns to the term, not the user
-
friendly label.

Tool

Read
Managed Metadata
Field

Update Managed
Metadata Field

SmartObject

Yes,
returns

Term GUID

No

List Item Wizard

Yes,
returns

Term GUID

Yes, with Term GUID

SharePoint Workflow Integration
(Process
Wizard
)

No (client event screen)

No (client event screen)

SharePoint Event Integration (Process
Wizard)

Yes,
returns

Term GUID in
event XML

N/A


Microsoft does

not support managed metadata in any Office 2010 client, with the exception of
Document Information Panes (DIPs) in InfoPath.

Managed metadata support in InfoPath would allow
fields to be validated against taxonomy values.

The Managed Metadata ServiceObject

The included sample project (with source code) implements a blackpearl ServiceObject for the
SharePoint Managed Metadata s
ervice. T
he

ServiceObject implements fo
u
r methods that can be used
to read information about TermSe
ts, Terms, and child Terms, but does

not provide capability to update
Terms. The sample source code is fully functional and can be freely modified to add a
dditional features.
Once invoked by a SmartObject, this service can be used within a workflow, or within any SmartObject
consumer to get information about terms. A
typical

use of this service would be to provide the ability to
create drop
-
down lists in I
nfoPath that use Terms or TermSets as the data source.

The ServiceObject uses a web service provided with SharePoint 2010 to get data. This web service is
located at
http://yo
ur.site/collection/_vti_bin/taxonomyclientservice.asmx
. Limited information about
this web service is available on MSDN. This web service is not like other SharePoint web services in that
it always returns
data as a
string. This string contains the Xm
l for complex types, but since the methods
to not return the actual type, the consuming application needs to be coded with knowledge of this
complex type. This means these web service methods cannot be easily consumed by InfoPath
or a
workflow
without
writing additional logic to consume the string and parse the Xml.

If these methods
returned a complex type instead of a string, it would be eas
ier

to consume. The
sample

ServiceObject
processes

the returned Xml string and returns it as a service instance

type that can be consumed by
SmartObjects (and their consumers) with no additional code.

The

sample

ServiceObject included with this document was built with SharePoint 2010
before

Service Pack 1. Future Service Pack s may change the taxonomyclientservic
e.asmx.

This
sample

was built and tested for K2 blackpearl 4.5 1370.

It is recommended to rebuild the sample code using a namespace that is consistent with your
organizational guidelines. The current namespace is K2
Field
.S
martObject
.Services.SharePointTa
xonomy.
This sample project is provided as an example and is not supported by SourceCode or the helpdesk.

Methods in ServiceObject

The following methods are provided in the
sample

ServiceObject and ca
n be invoked from a
SmartObject.

GetTerm

This method
returns 0 or more rows of information about a single term. A single term will generally only
return one row, but the method may return more than one row if the term has aliases. Each alias is a
different label for the term, but has the same Term ID.

Prop
erty

Type

Description

Input Properties



TermId (Required)

GUID

Unique identifier of the term
.

LocaleId (Optional
)

Number

T
he .NET Language identifier (
LCID
) that tells
what language
should be used for the term label
. If not specified, the Locale
specified when the service instance was registered will be
used.

Return Properties



TermId

GUID

Unique identifier of the term
.

TermSetId

GUID

Unique identifier of the
termset containing the term
.

Label

Text

The term label (user friendly name)
.

DefaultTerm

Boolean

True if this is the default term
label
; false if alias
.

HasChildTerms

Boolean

True if this term has child terms
.


GetTermSet

Gets a single row of information about the TermSet.

Property

Type

Description

Input Properties



Term
Set
Id (Required)

GUID

Unique identifier of the termset.

LocaleId (Optional
)

Number

The .NET Language identifier (
LCID
) that tells what language
should be used for the term label. If not specified, the Locale
specified when the service instance was registered will be
used.

Return
Properties



Description

Text

Description of the termset (if entered by the term owner).

Name

Text

Name of the termset.

SubmissionPolicy

Text

Submission policy of the term (Open or Closed).

Contact

Text

Email of the term owner (if entered).


GetChildTermsInTerm
Set

This method returns all of the immediate children of a term
set
, filtered by the optional label
.

To obtain
child terms of terms, use GetChildTermsInTerm.

Property

Type

Description

Input Proprerties



Term
Set
Id (Required)

GUID

Unique identifier of the termset.

LocaleId (Optional
)

Number

The .NET Language identifier (
LCID
) that tells what language
should be used for the term label. If not specifi
ed, the Locale
specified when the service instance was registered will be
used.

Label (Optional)

Text

If specified, the result list will be filtered to only return the
term in the set with the matching case
-
sensitive label.
Otherwise, all terms in the
set will be returned.

Return Properties



TermId

GUID

Unique identifier of the term.

TermSetId

GUID

Unique identifier of the termset containing the term.

Label

Text

The term label (user friendly name).

HasChildTerms

Boolean

True if this term has child

terms.


GetChildTermsInTerm

This method returns all of the immediate children of a term

filtered by the optional Label
. A term may
or may not have children. To obtain grandchild terms, call GetChildTermsInTerm with the appropriate
parent term Id.

Property

Type

Description

Input Properties



Term
Set
Id (Required)

GUID

Unique identifier of the termset.

TermId (Required)

GUID

Unique identifier of the term.

LocaleId (Optional
)

Number

The .NET Language identifier (
LCID
) that tells what language
should be used for the term label. If not specified, the Locale
specified when the service instance was registered will be
used.

Label (Option
al)

Text

If specified, the result list will be filtered to only return the
term in the set with the matching case
-
sensitive label.
Otherwise, all terms in the set will be returned.

Return Properties



TermId

GUID

Unique identifier of the term.

TermSetId

GUID

Unique identifier of the termset containing the term.

Label

Text

The term label (user friendly name).

HasChildTerms

Boolean

True if this term has child terms.

Deploying the Service
Object

Register ServiceType

The first step in deploying the ServiceObject is to register the Service Type.

1.

Copy the output assembly from the sample code to the ServiceBroker directory under the k2
blackpearl program files directory on
each

blackpearl host server:
{drive}:
\
{Program

Files}
\
K2
blackpearl
\
ServiceBroker
. If the sample namespace is not changed, the output assembly will be
K2
Field
.S
martObject
.Services.SharePointTaxonomy.dll
.

2.

The project contains an embedded WCF service binding that should work for most
environments
. However, if you need to customize the web service bindings for your
environment, you can deploy a file
with the same name as your assembly with an extension of
.config. For example,

K2
Field
.S
martObject
.Services.SharePointTaxonomy.dll.config
.

If you
c
hange the name of the output assembly, change the name of the config file to match your
assembly. If you wish to use the embededed version, you can change the endpoint address later
when you register the service instance. A sample WCF binding is shown be
low:










If you have large TermSets, you may need to increase the size of
maxReceivedMessageSize

in the
binding.

<?
xml

version
=
"
1.0
"

encoding
=
"
utf
-
8
"

?>

<
configuration
>


<
system.serviceModel
>


<
bindings
>


<
basicHttpBinding
>


<
binding

name
=
"
TaxonomyWebserviceSoap
"

closeTimeout
=
"
00:01:00
"


openTimeout
=
"
00:01:00
"

receiveTimeout
=
"
00:10:00
"

sendTimeout
=
"
00:01:00
"


allowCookies
=
"
false
"

bypassProxyOnLocal
=
"
false
"

hostNameComparisonMode
=
"
StrongWildcard
"


maxBufferSize
=
"
65536
"

maxBufferPoolSize
=
"
524288
"

maxReceivedMessageSi
ze
=
"
65536
"


messageEncoding
=
"
Text
"

textEncoding
=
"
utf
-
8
"

transferMode
=
"
Buffered
"


useDefaultWebProxy
=
"
true
"
>


<
readerQuotas

maxDepth
=
"
32
"

maxStringContentLength
=
"
8192
"

maxArrayLength
=
"
16384
"


maxBytesPerRead
=
"
4096
"

maxNameTableCharCount
=
"
16384
"

/>


<
security

mode
=
"
TransportCredentialOnly
"
>


<
transport

clientCredentialType
=
"
Ntlm
"

proxyCredentialType
=
"
None
"



realm
=
""

/>


<
message

clientCredentialType
=
"
UserName
"

algorithmSuite
=
"
Default
"

/>


</
security
>


</
binding
>


</
basicHttpBinding
>


</
bindings
>


<
client
>


<
endpoint

address
=
"
http://
your.site/collection/
_layouts/test/taxonomyclientservice.asmx
"


binding
=
"
basicHttpBinding
"

bindingConfiguration
=
"
TaxonomyWebserviceSoap
"


contract
=
"
TaxonomyClientService.TaxonomywebserviceSoap
"

name
=
"
TaxonomyWebserviceSoap
"

/>


</
client
>


</
system.serviceModel
>

</
configuration
>


3.

Open the SmartObject Service Tester generally found at
{drive}:
\
{Program Files}
\
K2
blackpearl
\
Bin
\
SmartObject Service Tester.exe.

a.

Click on
Register ServiceType
in the button bar

b.

From the Service dropdown list, choose your ServiceType. If your ServiceType
does not
show up in the list, you did not copy the assembly to the correct folder. Fill out the
remainder of the dialog with names and descriptions as appropriate for your
environment

and click
Add
.


Register Service Instance

Registering the service
instance joins the configuration data with the service. A service may have more
than one instance, each configured differently.

For example, you could have instances that point to
different TermStores or even different SharePoint
installations
.

1.


Using th
e SmartObject Service Tester, click
Register ServiceInstance

on the button bar.

a.

In the resulting dialog, choose
from
the
drop
-
down the
ServiceType you just registered.

b.

Chose the authentication method. The sample code supports
Impersonate

or
ServiceAccount
.

c.

Enter the GUID for the SharePoint
T
erm
S
tore that you will be querying. You will obtain
this information from SharePoint and it will
be unique to your environment. It will
not
match the screenshot below.

d.

Enter the Default Locale Id
(language code)
to re
trieve terms for. The default will be
used if you do not specify
optional
the locale when you invoke the service. The locale
will default to the language used when you installed K2 blackpearl.

e.

If you want the service to throw an exception if no results a
re found for a request,
change that configuration property to true. Otherwise, when it is false the service will
simply return no results.
Note: the SharePoint taxonomyclientservice may throw its
own exceptions which will be re
-
thrown by the service.

f.

E
nter a
Url for
a site collection containing managed metadata.
You must supply this
value if you are using the embedded WCF bindings, but it is not required if you supply
our own bindings config file as specified above.

Even if you supply your own binding
s,
this configuration item will override the value in the config file.

g.

Supply a binding name if you supplied your own WCF bindings config and it has more
than one binding entry.


2.


Click
Next

3.

In the resulting dialo
g, fill out appropriate names
and descript
ion.

4.

If this is the development environment, you should make note of the system generated GUID
that appears in this dialog. When you register this service instance in other environments like
test and production,
you must use the

same GUID

in all environme
nts
.


5.


Click
Add

6.

The new ServiceInstance is ready to be used.

SmartObjects

Now that the ServiceInstance is registered, you can create SmartObjects that invoke the service. You
can create SmartObjects using the SmartObject Service Tester, Visual Studio, or K2 Studio. For advanced
features, you must use Visual Studio or K2 Studio
. Once the SmartObject is created, you can use it in
any application that can consume SmartObjects.



You can integrate the SmartObject into InfoPath and use a Managed Metadata Term or TermSet
as the source for a dropdown list.



You can use the SmartObject

in conjunction with the List Item event wizard to update a column
with the GUID of a term when you only know the name.



You can use the SmartObject event wizard to return Metadata values for use in the workflow.



You can build a composite SmartObject that i
nvokes both the SharePoint service and this service
to translate the GUID value of a SharePoint Managed Metadata column into the label.

In order to invoke the various methods, you will need to
use

the GUIDs associated with the TermStore,
TermSet, and Terms

of interest. You can obtain these using the SharePoint
TaxonomyHiddenList

or by
looking at the Managed Metadata Service database for your installation.