README SAS Web Parts 1.1 for Microsoft SharePoint Description The SAS Web Parts for Microsoft SharePoint allow you to bring the power of SAS dashboards and SAS analytics to your SharePoint pages. This download currently includes two web parts: the SAS BI Dashboard Web Part and the SAS Stored Process Web Part. The BI Dashboard Web Part displays dashboards and KPIs at a glance to help users monitor organizational performance. Users can delve deeper into analysis using the SAS Stored Process Web Part and drill to other SAS BI tools and analytics products to gain additional insight. System Requirements Prerequisites Microsoft Windows Server 2003 or Microsoft Windows Server 2008 Windows SharePoint Services 3.0 or Microsoft Office SharePoint Server 2007 Microsoft.NET Framework 3.5 Service Pack 1, available from http://download.microsoft.com/download/2/0/e/20e90413-712f-438c- 988e-fdaa79a8ac3d/dotnetfx35.exe Microsoft Web Services Enhancements (WSE) 3.0 for Microsoft.NET, available from http://www.microsoft.com/downloads/details.aspx?displaylang=en&famil yid=018a09fd-3a74-43c5-8ec1-8d789091255d SAS Software Dependencies SAS Integration Technologies Client 9.2 Installable from your SAS Software Depot using the SAS Deployment Wizard. Contact your SAS Administrator for more information. Intended Audience This document is intended for individuals who are familiar with Microsoft SharePoint server administration and Microsoft Internet Information Server administration. The following assumptions are made: Windows SharePoint Services 3.0 or Microsoft Office SharePoint Server is installed and configured and running properly. You have privileges to log into the SharePoint server either directly from the console or using remote desktop. 1
You have permissions to add web parts to your SharePoint server and are familiar with doing so. You have experience creating and administering web sites in IIS Manager. Architectural Overview Security The SAS Web Parts for Microsoft SharePoint consists of two pieces: The Web Parts assembly (SAS.Webparts.dll) o must be installed on the SharePoint server The SAS Web Parts Service o runs in a separate IIS application from SharePoint o can be installed on the same machine as SharePoint o can be installed on a separate machine When considering where to install the SAS Web Parts Service, it is important to understand the topology of your network. The service must be able to connect to your SAS servers via SAS Integration Technologies, so there cannot be a firewall between the SAS Web Parts Service and your SAS servers. On the other hand, because the Web Parts connect to the service via SOAP over HTTPS, you can have a firewall between the SAS Web Parts Service and SharePoint. The simplest and most common deployment is to run the service on the SharePoint server. If there is no firewall to consider, this is the recommended setup. As of the release of these web parts, the 64 bit version of the SAS Integration Technologies Client 9.2 is not available. If you are using 64 bit hardware, it is important to note that the SAS Web Parts Service (which loads Integration Technologies Client 9.2) must run as a 32 bit application. In Internet Information Services (IIS) 6.0, the only way to run the SAS Web Parts Service as a 32 bit application is to force all IIS applications on that machine to run as 32 bit applications. Because this would require SharePoint to run as a 32 bit application, it is not possible to run the SAS Web Parts Service and SharePoint on the same 64 bit IIS 6.0 server. Under IIS 7.0 this is not an issue. IIS 7.0 allows each application pool to be set as 32 bit or 64 bit so the two applications can be placed in separate application pools. The SAS Web Parts must be configured with the DNS name and the port of the SAS Metadata Server and the SAS Trusted User ID and password. This information sits in the SharePoint web.config file. Although it is encrypted, care should be taken to limit access to the web.config file to prevent exposure of the password. The SAS Web Parts can access content on the SAS servers in either of two modes: actual identity or impersonation. By default, the user name of the SharePoint site visitor is used to authenticate with SAS, which provides the best security for the SAS content. Even if visitors have access to the SharePoint site, they might be denied access to the SAS content that is specified in the configuration of the Web Parts. The downside to this mode is that every site visitor must have an account on the SAS Metadata Server. 2
The alternative security mode is impersonation. In the web.config file, along with the SAS Trusted User credentials, an impersonation ID can be specified. If specified, that impersonation ID is used in place of the visitor s user name. As a result, only the single impersonation ID needs to exist in the metadata. When functioning in this mode, all visitors access the SharePoint site by using the same impersonation ID, so enforcement of more granular permissions is effectively delegated to SharePoint. Because of this, it is important that access to the SharePoint site or individual pages containing SAS Web Parts be carefully restricted to visitors who should be allowed to view the SAS content. Installation Instructions Downloading and Unzipping the SAS Web Parts Bundle Download the SASWebParts.zip file. Because the zip file includes configuration management scripts as well as the installation files for the service and the Web Parts, it is recommended that you unzip the contents of the file into a permanent location. 1. In your Program Files folder, create a new folder named SAS if one does not already exist. 2. Using WinZip or some similar tool, extract the contents of SASWebParts.zip into a permanent location, such as C:\Program Files\SAS. 3. Confirm that the following folders and files were created: Note: These files include both the SAS Web Parts and the SAS Web Parts Service, so the location of these files must be available to all machines involved in the setup and configuration. If you place the service on a machine other than the SharePoint server, you might need to unzip those files to both machines or temporarily share the location. Installing the SAS Web Parts Service The following steps must be performed on the machine on which you want the SAS Web Parts Service installed. 3
Creating the SAS Web Parts Service Site on IIS 6.0 1. Create the SASWebPartsService Web application in IIS. a. Select Start Administrative Tools Internet Information Services (IIS) Manager. b. In IIS window left pane, expand the local computer node. Right click on the Web Sites node and select New Web Site. Click Next. c. In the Description box, type SASWebPartsService. Click Next. d. In the TCP Port box, type 8888 (or any other unused port). Click Next. e. Click Browse and then select the location where you d like the Web service to be installed. (Typically, this location is C:\Inetpub\wwwroot.) f. In this location, create a new folder by clicking Make new Folder and typing SASWebPartsService. g. Click OK and confirm that the Path box displays the newly created folder (for example, C:\Inetpub\wwwroot\SASWebPartsService). Leave the Allow anonymous access to this website checkbox checked. Click Next. h. Select the Read and Run scripts permissions check boxes. Click Next. i. Click Finish. 2. Enable security on the newly created Web application. The connection between the SAS Web Parts to the SAS Web Parts Service requires transport layer security (HTTPS). To achieve this, you must attach an SSL server certificate to the newly created SAS Web Parts Service application. Note: Because the procedure for procuring a certificate varies from company to company, instructions on how to do so are not included here. Contact your site security administrator. 3. After you have an SSL server certificate, attach the security certificate as follows: a. In the IIS Manager, right click the SASWebPartsService Web site and select Properties. b. In the Properties dialog box on the Directory Security tab, click Server Certificate. c. On the second page of the IIS Certificate Wizard, select Process the pending request and install the certificate. Click Next. d. Specify the location of the certificate in the Path and filename box. Click Next. e. You can accept the default value of 443 as the SSL port. f. On the Summary page, click Next to install the certificate. g. Click Finish to close the wizard. Creating the SAS Web Parts Service Site on IIS 7.0 1. The connection between the SAS Web Parts to the SAS Web Parts Service requires transport layer security (HTTPS). To achieve this, you must attach an SSL server certificate to the SAS Web Parts Service application. Note: Because the procedure for procuring a certificate varies from company to company, Instructions on how to do so are not included here. Contact your site security administrator. 2. After you have an SSL server certificate, attach the security certificate as follows: a. In the IIS Manager, click on the machine name in the Connections pane on the left. b. In the Features View, double click on Server Certificates. 4
c. In the Actions pane on the left side, click Complete Certificate Request d. In the Complete Certificate Request dialog, provide the full path to the certificate file and a friendly name. Click OK. 3. Create the SASWebPartsService Web application in IIS. a. Select Start Administrative Tools Internet Information Services (IIS) Manager. b. In IIS window left pane, expand the local computer node. Right click on the Sites node and select Add Web Site c. In the Site name box, type SASWebPartsService. d. Click the browse ( ) button beside the Physical path box and then select the location where you d like the Web service to be installed. (Typically, this location is C:\Inetpub\wwwroot.) e. In this location, create a new folder by clicking Make new Folder and typing SASWebPartsService. f. Click OK and confirm that the Physical path box displays the newly created folder (for example, C:\Inetpub\wwwroot\SASWebPartsService). g. In the Type drop down, select https. h. In the SSL certificate drop down, select the certificate that you added previously and click OK. Installing and Confirming the SAS Web Parts Service 1. Install the SAS Web Parts Service. a. Run ServiceSetup.bat located in the folder where you previously unzipped the SASWebParts.zip file (C:\Program Files\SAS\SASWebParts\1.1\ ServiceSetup.bat). Click Next. b. From the Site drop down list on the Select Installation Address page, change the value from Default Web Site to SASWebPartsService. Leave the other values as they are (the Site and Virtual Directory boxes will contain the same value). Click Next. c. On the Confirm Installation page, click Next to confirm the installation. d. Click Close to complete the setup. 2. If you are running the SAS Web Parts Service on a 64 bit machine and using the 32 bit version of SAS Integration Technologies Client 9.2, the service must run as a 32 bit application. You can determine which version of SAS Integration Technologies Client is available by looking at the path where it is installed. On a 64 bit machine, the 32 bit version is installed in \Program Files (x86)\sas\sharedfiles\integration Technologies or \Program Files\SAS\SharedFiles(32)\Integration Technologies. The 64 bit version is installed in the \Program Files\SAS\SharedFiles\Integration Technologies. Enabling 32 Bit Applications on IIS 6.0 In IIS 6.0, the only way to run the SAS Web Parts Service as a 32 bit application is to force all IIS applications on that machine to run as 32 bit applications. Because this would cause SharePoint to run as a 32 bit application if it were running on the same machine, it is not recommended that you run the SAS Web Parts Service and SharePoint on the same 64 bit IIS 6.0 server. To enable the SAS Web Parts Service to run as a 32 bit application, follow these steps: a. Open a command prompt. b. Run the following command: 5
cscript %SystemDrive%\inetpub\AdminScripts\adsutil.vbs set w3svc/apppools/enable32bitapponwin64 1 Enabling 32 Bit Applications on IIS 7.0 a. Open IIS Manager. b. In the left pane s tree view, navigate to <Machine Name>\Web Sites\SASWebPartsService. c. Click on the SASWebPartsService application (the application node icon has a globe overlaid with pages. It is a child of the SASWebPartsService site.) d. In the Actions pane on the right side of IIS Manager, click on Advanced Settings e. Under the (General) heading, note the Application Pool setting. This is the application pool in which the SASWebPartsService is running. Close the dialog by pressing Cancel. f. Again in IIS Manager s left pane, click on Application Pools. g. In the Features View, click on the application pool that you identified in the previous step. h. In the Actions pane, click on Advanced Settings i. In the Advanced Settings dialog under the (General) header, set Enable 32 Bit Applications to True. j. Click OK to save the setting and close the dialog. 3. In a browser window, confirm that the service is up and running by opening the service: https://<machinename>/saswebpartsservice/service.svc 4. Confirm that there are no security certificate warnings. The page should look similar to this: 6
Installing and Configuring the SAS Web Parts With the SAS Web Parts Service installed, you are ready to deploy the SAS Web Parts in SharePoint and configure them. The following steps should be performed on the machine on which SharePoint is running. Configuration can be performed either by opening WebPartsSetup.bat with a text editor and setting the values in the file, saving it, and then running the script or by passing arguments to WebPartsSetup.bat. Install By Editing WebPartsSetup.bat Script 1. Open WebPartsSetup.bat in notepad or some other text editor, located in the folder where you previously unzipped the SASWebParts.zip file (C:\Program Files\SAS\SASWebParts\1.1\WebPartsSetup.bat). 2. Near the top of the file, in the Init section, type the appropriate values for the configuration settings: SasServer=<machine> Name of the SAS Metadata Server SasPort=<port> (optional, default: 8561) Port of the SAS Metadata Server. TrustedUser=<userid> (optional, default: sastrust@saspw) SAS Trusted User ID as defined in metadata (default: sastrust@saspw). This is not your personal login ID. This ID will be used to connect to the SAS Metadata Server and acts on behalf of other users. If you are unsure of the SAS Trusted User ID, contact your SAS administrator or see the SAS Metadata Server Setup and Administration Guide. TrustedPassword=<password> Password for the SAS Trusted User ID ServiceUrl=<url> URL of the SAS Web Parts Service (https://<machinename>/saswebpartsservice/service.svc) ImpersonationId=<userid> (optional) ID to be used for all SharePoint site visitors to access SAS content. A login for this ID must exist on the SAS Metadata Server (see the ʺSecurityʺ section above for further explanation). WebUrl=<url> (optional, default: http://localhost) URL of the SharePoint Server SiteUrl=<url> (optional, default: http://localhost) URL of the SharePoint Server site WssPort=<port> (optional, default: 80) Port of the SharePoint Server Encrypt=true false Once the configuration settings are placed in the web.config file, encrypt the section containing those settings. Preview=true false Instead of updating the web.config file, makes a copy of the web.config file (named web.config.preview) and updates the copy. The settings are left unencrypted! SiteDir=<path> (optional) Path to the location of the SharePoint site directory (default: c:\inetpub\wwwroot\wss\virtualdirectories\80) 7
Install Using Command-Line Arguments 1. Open a command prompt by selecting Start Run. Then type cmd.exe in the Open box and click OK. 2. At the command prompt, type cd c:\program Files\SAS\SASWebParts\1.1 to change the directory to the folder in which you unzipped the downloaded install bundle. 3. Run WebPartsSetup.bat with the following arguments: /sasserver <machine> Name of the SAS Metadata Server /sasport <port> (optional) Port of the SAS Metadata Server (default: 8561) /trusteduser <userid> (optional) SAS Trusted User ID as defined in metadata (default: sastrust@saspw). This is not your personal login ID. This ID will be used to connect to the SAS Metadata Server and acts on behalf of other users. If you are unsure of the SAS Trusted User ID, contact your SAS administrator or see the SAS Metadata Server Setup and Administration Guide. /trustedpassword <password> Password for the SAS Trusted User ID /serviceurl <url> URL of the SAS Web Parts Service (https://<machinename>/saswebpartsservice/service.svc) /impersonationid <userid> (optional) ID to be used for all SharePoint site visitors to access SAS content. A login for this ID must exist on the SAS Metadata Server (see the ʺSecurityʺ section above for further explanation). /weburl <url> (optional) URL of the SharePoint Server (default: http://localhost) /siteurl <url> (optional, default: http://localhost) URL of the SharePoint Server site /wssport <port> (optional) Port of the SharePoint Server (default: 80) /encrypt or /decrypt Once the configuration settings are placed in the web.config file, encrypt the section containing those settings. /preview (optional) Instead of updating the web.config file, makes a copy of the web.config file (named web.config.preview) and updates the copy. /sitedir <path> (optional) Path to the location of the SharePoint site directory (default: c:\inetpub\wwwroot\wss\virtualdirectories\80) Examples: WebPartsSetup.bat /sasserver server01 /trustedpassword Password1 /serviceurl https://machine.domain.com/saswebpartsservice/service.svc 8
WebPartsSetup.bat /sasserver server01 /sasport 8561 /trusteduser sastrust@saspw /trustedpassword Password1 /impersonationid sharepointuser /weburl http://sharepoint.domain.com /serviceurl https://machine.domain.com/saswebpartsservice/service.svc SAS BI Dashboard Configuration Because the SharePoint Server is acting as a trusted peer to the SAS BI Dashboard Server, you must modify the SAS BI Dashboard configuration to include the name of the SharePoint server. To make this change, you must have administrative privileges on the SAS Metadata server and access to SAS Management Console. 1. Run SAS Management Console by selecting Start All Programs SAS SAS Management Console 9.2. 2. Log on to your SAS Metadata Server. 3. On the Plug ins tab in the left pane, expand the Application Management folder and then the Configuration Manager folder. 4. Right click the BI Dashboard 4.2 folder and select Properties. 5. In the BI Dashboard 4.2 Properties dialog box, select the Advanced tab. 6. Modify the bid.midtier.trusted.urls property value to include the name and port of the SharePoint server (the values in this list are separated by commas). 7. Click OK. 8. Restart the SAS BI Dashboard web application server. 9. The SAS Web Parts are ready for deployment. Reconfiguring the SAS Web Parts If the SAS Server location changes or if the SAS Trusted User ID or password is changed in the SAS Metadata Server, you must reconfigure the SAS Web Parts with the updated information. To reconfigure the SAS Web Parts, the following steps should be performed on the machine on which SharePoint is running. As with the initial installation, reconfiguration can be performed either by opening WebPartsSetup.bat with a text editor and setting the values in the file, saving it, and then running the script or by passing arguments to WebPartsSetup.bat. Reconfiguration by Editing WebPartsSetup.bat Script 1. Open WebPartsSetup.bat in notepad or some other text editor, located in the folder where you previously unzipped the SASWebParts.zip file (C:\Program Files\SAS\SASWebParts\1.1\WebPartsSetup.bat). 2. Near the top of the file, in the Init section, type the appropriate values for the configuration settings. Settings left blank will cause reuse of the settings previously defined in web.config file: Reconfig=true SasServer=<machine> (optional, reuse existing value if left blank) Name of the SAS Metadata Server SasPort=<port> (optional, reuse existing value if left blank) Port of the SAS Metadata Server. 9
TrustedUser=<userid> (optional, reuse existing value if left blank) SAS Trusted User ID as defined in metadata (default: sastrust@saspw). This is not your personal login ID. This ID will be used to connect to the SAS Metadata Server and acts on behalf of other users. If you are unsure of the SAS Trusted User ID, contact your SAS administrator or see the SAS Metadata Server Setup and Administration Guide. TrustedPassword=<password> (optional, reuse existing value if left blank) Password for the SAS Trusted User ID ServiceUrl=<url> (optional, reuse existing value if left blank) URL of the SAS Web Parts Service (https://<machinename>/saswebpartsservice/service.svc) ImpersonationId=<userid> (optional, reuse existing value if left blank) ID to be used for all SharePoint site visitors to access SAS content. A login for this ID must exist on the SAS Metadata Server (see the ʺSecurityʺ section above for further explanation). WebUrl=<url> (optional, default: http://localhost) URL of the SharePoint Server SiteUrl=<url> (optional, default: http://localhost) URL of the SharePoint Server site WssPort=<port> (optional, default: 80) Port of the SharePoint Server SiteDir=<path> (optional) Path to the location of the SharePoint site directory (default: c:\inetpub\wwwroot\wss\virtualdirectories\80) Reconfiguration Using Command-Line Arguments 1. Open a command prompt by selecting Start Run. Then type cmd.exe in the Open box and click OK. 2. At the command prompt, type cd \Program Files\SAS\SASWebParts\1.1 to change the directory to the folder in which you unzipped the downloaded install bundle. 3. Run WebPartsSetup.bat with the following arguments. You only need to specify the arguments whose values are changing. /reconfig /sasserver <machine> Name of the machine where SAS Metadata Server is running /sasport <port> Port on which SAS Metadata Server is running /trusteduser <userid> SAS Trusted User ID as defined in metadata (default: sastrust@saspw). This is not your personal login ID. This ID will be used to connect to the SAS Metadata Server and acts on behalf of other users. If you are unsure of the SAS Trusted User ID, contact your SAS administrator or see the SAS Metadata Server Setup and Administration Guide. /trustedpassword <password> Password for the SAS Trusted User ID /impersonationid <userid> (optional) ID to be used for all SharePoint site visitors to access SAS content. A login for this ID must exist on the SAS Metadata Server. (See the section on Security for further explanation.) 10
/weburl <url> (optional) URL of the SharePoint Server (default: http://localhost) /siteurl <url> (optional, default: http://localhost) URL of the SharePoint Server site /wssport <port> (optional, default: 80) Port of the SharePoint Server /sitedir <path> (optional) Path to the location of the SharePoint site directory (default: c:\inetpub\wwwroot\wss\virtualdirectories\80) Uninstalling the SAS Web Parts To remove the SAS Web Parts from your SharePoint server, perform the following steps on the machine on which SharePoint is running. As with the initial installation, reconfiguration can be performed either by opening WebPartsSetup.bat with a text editor and setting the values in the file, saving it, and then running the script or by passing arguments to WebPartsSetup.bat. Uninstall by Editing WebPartsSetup.bat Script 1. Open WebPartsSetup.bat in notepad or some other text editor, located in the folder where you previously unzipped the SASWebParts.zip file (C:\Program Files\SAS\SASWebParts\1.1\WebPartsSetup.bat). 2. Near the top of the file, in the Init section, type the appropriate values for the configuration settings. Settings left blank will cause reuse of the settings previously defined in web.config file: Uninstall=true Reconfig=false WebUrl=<url> (optional, default: http://localhost) URL of the SharePoint Server SiteUrl=<url> (optional, default: http://localhost) URL of the SharePoint Server site WssPort=<port> (optional, default: 80) Port of the SharePoint Server SiteDir=<path> (optional) Path to the location of the SharePoint site directory (default: c:\inetpub\wwwroot\wss\virtualdirectories\80) Uninstalling Using Command-Line Arguments 1. Open a command prompt by selecting Start Run. Then type cmd.exe in the Open box and click OK. 2. At the command prompt, type cd \Program Files\SAS\SASWebParts\1.1 to change the directory to the folder in which you unzipped the downloaded install bundle. 3. Run WebPartsSetup.bat with the following arguments: /uninstall 11
/weburl <url> (optional) URL of the SharePoint Server (default: http://localhost) /siteurl <url> (optional, default: http://localhost) URL of the SharePoint Server site /wssport <port> (optional, default: 80) Port of the SharePoint Server /sitedir <path> (optional) Path to the location of the SharePoint site directory (default: c:\inetpub\wwwroot\wss\virtualdirectories\80) Remove the Web Parts from the Gallery list 1. In your browser, open the Site Settings page for the Site Collection. 2. Under the Galleries heading, click Web Parts. 3. In the Web Parts Gallery, click the edit icon beside the DashboardWebPart.webpart entry. 4. In the edit item page, click Delete Item at the top of the form. 5. Click OK to confirm that you d like the delete the item. 6. Once again in the Web Parts Gallery, click the edit icon beside the StoredProcessWebPart.webpart entry. 7. In the edit item page, click Delete Item at the top of the form. 8. Click OK to confirm that you d like the delete the item. Uninstalling the SAS Web Parts Service To remove the SAS Web Parts Service from your server, perform the following steps on the machine on which the service is running. 1. Open Control Panel and select Add or Remove Programs. 2. Select SASWebPartsService in the list and click on Remove. 3. When prompted to confirm that you are sure you want to remove SASWebPartsService from your computer, click Yes. 4. When the installer finishes removing the SASWebPartsService, close the dialog. 5. Select Start Administrative Tools Internet Information Services (IIS) Manager. 6. In IIS window left pane, expand the local computer node and the Web Sites node. 7. Right click on the SASWebPartsService node and select Remove or Delete and confirm that you d like to remove the site. SAS and all other SAS Institute product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. Other brand and product names are registered trademarks or trademarks of their respective companies. indicates USA registration. Copyright 2009 SAS Institute Inc., Cary, NC, USA. All rights reserved. 12 11 June 2009