Using the API Objects in Visual Studio
A Visual Studio project must reference the BlueThread.SharePoint.StoragePoint.StoragePointAPI assembly in order to use the ProfileAPI class. This assembly is installed by the core StoragePoint installation in the SharePoint bin directory (ex. C:\Program Files\Common Files\Web Server Extension\12\bin if SharePoint is installed on the C drive). To set the reference in Visual Studio:
1)Right click on the References node under the custom project.
2)Select the Browse tab and browse to the SharePoint bin directory (see above).
3)Select the file Bluethread.SharePoint.StoragePoint.StoragePointAPI.dll and click OK.
Also note the following limitations on solutions developed using the classes:
·The solution must run on a SharePoint WFE server in the farm. No provision is made for access by machines outside of the farm.
·Use outside of a SharePoint context is not supported.
·The solution should run under the SharePoint service account so that access to SharePoint resources and databases is possible.
Profile Creation API
The ProfileAPI object allows the creation of StoragePoint externalization profiles outside of the StoragePoint UI. This object is usable only from Microsoft .net code.
ProfileAPI Object Reference
Constructor Reference
The ProfileAPI object is created by one of three constructors. The first in the table below is the constructor to use to create a new profile. The other two are used only for loading existing profiles.
|
Constructor Signature |
Description |
|
ProfileAPI(ProfileType type, string scopeId)
|
Used to create a profile on a given site collection, content database or web application (or a no-scope profile). If type is SiteCollection, then scopeId should be the ID value of the SPSite object for the site collection. If type is WebApplication then scopeId should be the Id value of the SPWebApplication object for the web application. If type is NoScope, then scopeId should be null. |
|
ProfileAPI(string ProfileId) |
Used to load a profile given its unique ProfileId identifier. Cannot be used to create a new profile. |
|
ProfileAPI(SPListItem listItem) |
Used to load the profile for a given document (identified by its SPListItem object). Cannot be used to create a new profile. |
Property Reference
The ProfileAPI object has many properties that can be set to enable various profile options. Most of these options correspond to items presented in the Add/Edit Profile page in StoragePoints management console.
|
Property Name |
Data Type |
Required |
Description |
|
IsActive |
bool |
Yes |
Specifies whether the profile should externalize content or not. Should generally set to True. |
|
AdapterName |
string |
Yes |
The storage adapter to use for the profile. Possible values include FileSystem, Atmos, AmazonS3, Azure, EMCCentera, HcapRest and Rackspace (note that all but FileSystem require a separate purchase of the given adapter). FileSystem should be used to store content on file shares or most SAN devices. |
|
Connection |
string |
Yes |
The adapter specific connection string. |
|
UseCompression |
bool |
No |
Specifies whether compression is turned on for the profile. Set to true to turn on compression. Default is false. |
|
UseEncryption |
bool |
No |
Specifies whether encryption is turned on for the profile. Set to true to enable (default is false). By default, when enabling encryption, the profile will be automatically set to use 256-bit AES encryption. This can be overridden via the EncryptionProviderId property. |
|
EncryptionPassphrase |
string |
No (unless UseEncryption set) |
A password that will be used to generate an encryption key. Must be set if UseEncryption property is set to true. |
|
EncryptionProviderId |
string |
No |
The guid-style identifier of the encryption profile to use. This does not need to be set if the default AES 256-bit provider is desired. This id value can be obtained by examining the EncryptionProviders table in the StoragePoint database. |
|
ProfileId |
string |
No |
The internal guid-style identifier of the profile. Will be NULL for any new profile (until Save is called). |
|
Type |
ProfileType |
Yes in constructor |
The type of the profile. Can be: SiteCollection for site collection profiles. WebApplication for web app profiles. NoScope for scope-less profiles. This property is read-only. The type of the profile being created is specified in the constructor of the ProfileAPI class. |
|
SiteId |
string |
Yes in constructor |
The id of site collection that the profile is attached to (for SiteCollection type profiles). This is set in the constructor of the ProfileAPI class. |
|
WebApplicationId |
string |
Yes in constructor |
The id of web application that the profile is attached to (for WebApplication type profiles). This is set in the constructor of the ProfileAPI class. |
|
BlobRetentionDays |
int |
No |
Number of days after a BLOB file has been orphaned that it should be kept. |
|
Foldering |
Bool |
No |
Specifies if content should be auto-foldered on the external file store (not in SharePoint see CabinetOn for that). Default is true. Leaving this setting on true is highly recommended. |
|
FolderingLevel |
int |
No |
Specifies the format of the auto foldering scheme. Default value is 5. Possible values are: 1 for YYYY 2 for YYYY/MM 3 for YYYY/MM/DD 4 for YYYY/MM/DD/HH 5 for YYYY/MM/DD/HH/MM 6 for YYYY/MM/DD/HH/MM/SS |
|
FileSizeOp |
int |
No |
Specifies the operator to use if a file size filter is specified. Possible values are: 0 for less than or equal to (<=) 1 for greater than or equal to (>=) |
|
FileSize |
int |
No |
The file size in KB if a file size filter is specified. -1 (negative one) means no file size filter is in place and is the default value. |
|
FileTypeOp |
int |
No |
Specifies the operator to use if a file type filter is specified. Possible values are: 0 for Exclude specified file types 1 for Include specified file types |
|
FileTypes |
string |
No |
A comma separated list of file types in the filter. The file type must be UPPER case and be the correct extension for the file type. For example, TIF for TIFF files or PPTX for PowerPoint files. Separate multiple file types by commas (,). The value should be null (the default) if no file type filter is desired. |
|
RMEnabled |
bool |
No |
Specifies whether Records Management is enabled. |
|
RMScope |
string |
No |
Scope of the Records Management rules. |
|
RMDeclaredRecord |
bool |
No |
Whether declaring a record moves the BLOB. |
|
RMDeclaredRecordEndpoint |
EndpointAPI |
No |
The endpoint which stores the BLOB of a record. |
|
RMUndeclaredRecord |
bool |
No |
Whether undeclaring a record moves the BLOB. |
|
RMUndeclaredRecordEndpoint |
EndpointAPI |
No |
The endpoint which stores the BLOB that is no longer a record. |
|
HMEnabled |
bool |
No |
Specifies whether Holds Management is enabled. |
|
HMScope |
string |
No |
Scope of the Holds Management rules. |
|
HMOnHold |
bool |
No |
Whether putting an item in hold moves the BLOB. |
|
HMOnHoldEndpoint |
EndpointAPI |
No |
The endpoint which stores the BLOB of an item in hold. |
|
HMRemovedFromHold |
bool |
No |
Whether removing a file from hold moves the BLOB. |
|
HMRemovedFromHoldEndpoint |
EndpointAPI |
No |
The endpoint which stores the BLOB that is no longer in a hold. |
Method Reference
There are a few methods provided in the ProfileAPI object to accomplish certain tasks. The following methods are available:
|
Method Name |
Parameters |
Description |
|
Save |
(none) |
Saves the profile and activates if (if necessary) on the specified site collection or web application. |
|
Test |
(none) |
Tests the profile by writing out a small test file and then deleting it. Will throw an exception if anything goes wrong. |
|
Delete |
int recallJobThreads -> Number of threads to allocate to the recall job that is scheduled by the delete.
string notificationEmailAddress -> Email address to send completion email to when delete and recall are complete.. |
Schedules a deletion of the profile. Deletion of a profile requires a recall job to run first. Thus, this method returns before the deletion is complete. |
|
CreateOrphanBlobCleanupJob |
SPSchedule schedule -> Specifies the schedule of when to run the job. Can be any of the SharePoint SPSchedule derived types such as SPDailySchedule or SPWeeklySchedule.
string emailNotificationAddress -> Specifies the email address to send the job completion email to. Pass null if no email is desired.
bool emailOnErrorOnly -> true to send completion email on error only and false to send always. |
Creates an Orphan BLOB Cleanup Job (garbage collector) for the profile. |
Profile Creation Code Examples
The following are examples in Microsoft C# of creating various types of StoragePoint profiles. A good strategy for creating Profile API code is to take one of these samples and customize it as needed. For example, to create a profile with encryption but not compression support, simply take the Creating a Profile with Encryption and Compression example and delete the line profile.UseCompression = true;.
|
|
NOTE: All examples assume the presence of an SPSite object named site (for site collection profile examples) or an SPWebApplication object named webapp (for web application examples). These are used solely to obtain the Id value of the given site or web application. The Id value may be obtained in other ways or even hard-coded if desired. |
Creating a Site Collection Profile with No Encryption or Compression (C#)
This example creates a basic profile on a site collection. It uses the included FileSystem adapter and does not enable compression and encryption support.
ProfileAPI profile =
new ProfileAPI(ProfileAPI.ProfileType.SiteCollection,
site.ID.ToString());
profile.IsActive = true; // Profile should externalize content
profile.AdapterName = "FileSystem";
profile.Connection = "path=e:\\ExternalFileStore";
profile.Save();
Creating a Web Application Profile with No Encryption or Compression (C#)
This example creates a basic profile (similar to the last example) on a Web Application.
ProfileAPI profile =
new ProfileAPI(ProfileAPI.ProfileType.WebApplication,
webapp.Id.ToString());
profile.IsActive = true; // Profile should externalize content
profile.AdapterName = "FileSystem";
profile.Connection = "path=e:\\ExternalFileStore";
profile.Save();
Creating a Profile with Encryption and Compression (C#)
This example builds on the previous examples to include compression and encryption support. This example may be used on a web application by modifying the first line to create a ProfileType.WebApplication type profile (see the last example).
ProfileAPI profile =
new ProfileAPI(ProfileAPI.ProfileType.SiteCollection,
site.ID.ToString());
profile.IsActive = true; // Profile should externalize ntent
profile.AdapterName = "FileSystem";
profile.Connection = "path=e:\\ExternalFileStore";
profile.UseCompression = true;
profile.UseEncryption = true;
profile.EncryptionPassphrase = "your_unique_passphrase_here";
profile.Save();
Creating a Web Application Profile with a File Type and File Size Filter (C#)
This example creates a basic profile (similar to the last example) on a Web Application.
ProfileAPI profile =
new ProfileAPI(ProfileAPI.ProfileType.WebApplication,
webapp.Id.ToString());
profile.IsActive = true; // Profile should externalize content
profile.AdapterName = "FileSystem";
profile.Connection = "path=e:\\ExternalFileStore";
profile.FileSizeOp = 1; // >=
profile.FileSize = 40; // 40k
profile.FileTypeOp = 1; // Include
profile.FileTypes = "TIF,PPTX"; // TIFF and powerpoint files
profile.Save();
Creating a Scope-less Profile with No Encryption or Compression (C#)
This example creates a scope-less profile that stores externalized content on an EMC Atmos cloud account (requires the Atmos cloud adapter for StoragePoint and an EMC Atmos online account). A scope-less profile can only be used to externalize content from a workflow or other custom code (like a custom event receiver).
ProfileAPI profile = new ProfileAPI(ProfileAPI.ProfileType.NoScope,null);
profile.IsActive = true;
profile.AdapterName = "Atmos";
profile.Connection ="UID=atmos user id;Key=atmos secret key;";
profile.UseCompression = true;
profile.UseEncryption = true;
profile.EncryptionPassphrase = "your_unique_passphrase_here";
profile.Save();
Deleting a Profile (C#)
This example loads an existing profile and schedules it for deletion.
ProfileAPI p =
new ProfileAPI("81d2fa85-365d-4e56-8820-295f9cdd1aa5");
p.Delete(4, "admin@storagepoint.local");