How to: Create a provider-hosted app for SharePoint to access SAP data via SAP Gateway for Microsoft

You can create an app for SharePoint that reads and writes SAP data, and optionally reads and writes SharePoint data, by using SAP Gateway for Microsoft and the Azure AD Authentication Library for .NET. This article provides the procedures for how you can design the app for SharePoint to get authorized access to SAP.

Before you begin

---

The following are prerequisites to the procedures in this article:

• An Office 365 Developer Site in an Office 365 domain that is associated with a Microsoft Azure Active Directory subscription. See Sign up for an Office 365 Developer Subscription, set up your tools and environment, and start deploying apps or How to: Create a Developer Site within your existing Office 365 subscription.
• Visual Studio 2013 Update 2 or later, which you can obtain from Welcome to Visual Studio 2013.
• Microsoft Office Developer Tools for Visual Studio. The version that is included in Update 2 of Visual Studio 2013 or later.
• SAP Gateway for Microsoft is deployed and configured in Microsoft Azure. See the documentation for SAP Gateway for Microsoft.
• An organizational account in Microsoft Azure. See http://msdn.microsoft.com/en-us/library/office/dn605894(v=office.15).aspx#bk_CreateOrganizationAccount.

  Note
  Login to your Office 365 account (login.microsoftonline.com) to change the temporary password after the account is created.

• A SAP OData endpoint with sample data in it. See the documentation for SAP Gateway for Microsoft.

• A basic familiarity with Azure AD. See Getting started with Azure AD.
• A basic familiarity with creating apps for SharePoint. See How to: Create a basic provider-hosted app for SharePoint.
• A basic familiarity OAuth 2.0 in Azure AD. See OAuth 2.0 in Azure AD and its child topics.

Code sample: SharePoint 2013: Using the SAP Gateway to Microsoft in an app for SharePoint

Understand authentication and authorization to SAP Gateway for Microsoft and SharePoint

---

OAuth 2.0 in Azure AD enables applications to access multiple resources hosted by Microsoft Azure and SAP Gateway for Microsoft is one of them. With OAuth 2.0, applications, in addition to users, are security principals. Application principals require authentication and authorization to protected resources in addition to (and sometimes instead of) users. The process involves an OAuth “flow” in which the application, which can be an app for SharePoint, obtains an access token (and refresh token) that is accepted by all of the Microsoft Azure-hosted services and applications that are configured to use Azure AD as an OAuth 2.0 authorization server. The process is very similar to the way that the remote components of a provider-hosted app for SharePoint gets authorization to SharePoint as described in Creating apps for SharePoint that use low-trust authorization and its child articles. However, the ACS authorization system uses Microsoft Azure Access Control Service (ACS) as the trusted token issuer rather than Azure AD.

Tip

If your app for SharePoint accesses SharePoint in addition to accessing SAP Gateway for Microsoft, then it will need to use both systems: Azure AD to get an access token to SAP Gateway for Microsoft and the ACS authorization system to get an access token to SharePoint. The tokens from the two sources are not interchangeable. For more information, see Optionally, add SharePoint access to the ASP.NET application.

For a detailed description and diagram of the OAuth flow used by OAuth 2.0 in Azure AD, see Authorization Code Grant Flow. (For a similar description, and a diagram, of the flow for accessing SharePoint, see See the steps in the Context Token flow.)

Create the app for SharePoint

---

Create the Visual Studio solution

1. Create an App for SharePoint project in Visual Studio with the following steps. (The continuing example in this article assumes you are using C#; but you can start an app for SharePoint project in the Visual Basic section of the new project templates as well.)
   1. In the New app for SharePoint wizard, name the project and click OK. For the continuing example, use SAP2SharePoint.
   2. Specify the domain URL of your Office 365 Developer Site (including a final forward slash) as the debugging site; for example, https://<O365_domain&gt;.sharepoint.com/. Specify Provider-hosted as the app type. Click Next.
   3. Choose a project type. For the continuing example, choose ASP.NET Web Forms Application. (You can also make ASP.NET MVC applications that access SAP Gateway for Microsoft.) Click Next.
   4. Choose Azure ACS as the authentication system. (Your app for SharePoint will use this system if it accesses SharePoint. It does not use this system when it accesses SAP Gateway for Microsoft.) Click Finish.
2. After the project is created, you are prompted to login to the Office 365 account. Use the credentials of an account administrator; for example Bob@<O365_domain>.onmicrosoft.com.
3. There are two projects in the Visual Studio solution; the app for SharePoint proper project and an ASP.NET web forms project. Add the Active Directory Authentication Library (ADAL) package to the ASP.NET project with these steps:
   1. Right-click the References folder in the ASP.NET project (named SAP2SharePointWeb in the continuing example) and select Manage NuGet Packages.
   2. In the dialog that opens, select Online on the left. Enter Microsoft.IdentityModel.Clients.ActiveDirectory in the search box.
   3. When the ADAL library appears in the search results, click the Install button beside it, and accept the license when prompted.
4. Add the Json.net package to the ASP.NET project with these steps:
   1. Enter Json.net in the search box. If this produces too many hits, try searching on Newtonsoft.json.
   2. When Json.net appears in the search results, click the Install button beside it.
5. Click Close.

Register your web application with Azure AD

1. Login into the Azure Management portal with your Azure administrator account.

   Note
   For security purposes, we recommend against using an administrator account when developing apps.

2. Choose Active Directory on the left side.
3. Click on your directory.
4. Choose APPLICATIONS (on the top navigation bar).
5. Choose Add on the toolbar at the bottom of the screen.
6. On the dialog that opens, choose Add an application my organization is developing.
7. On the ADD APPLICATION dialog, give the application a name. For the continuing example, use ContosoAutomobileCollection.
8. Choose Web Application And/Or Web API as the application type, and then click the right arrow button.
9. On the second page of the dialog, use the SSL debugging URL from the ASP.NET project in the Visual Studio solution as the SIGN-ON URL. You can find the URL using the following steps. (You need to register the app initially with the debugging URL so that you can run the Visual Studio debugger (F5). When your app is ready for staging, you will re-register it with its staging Azure Web Site URL. Modify the app and stage it to Azure and Office 365.)
   1. Highlight the ASP.NET project in Solution Explorer.
   2. In the Properties window, copy the value of the SSL URL property. An example is https://localhost:44300/.
   3. Paste it into the SIGN-ON URL on the ADD APPLICATION dialog.
10. For the APP ID URI, give the application a unique URI, such as the application name appended to the end of the SSL URL; for example https://localhost:44300/ContosoAutomobileCollection.
11. Click the checkmark button. The Azure dashboard for the application opens with a success message.
12. Choose CONFIGURE on the top of the page.
13. Scroll to the CLIENT ID and make a copy of it. You will need it for a later procedure.
14. In the keys section, create a key. It won’t appear initially. Click SAVE at the bottom of the page and the key will be visible. Make a copy of it. You will need it for a later procedure.
15. Scroll to permissions to other applications and select your SAP Gateway for Microsoft service application.
16. Open the Delegated Permissions drop down list and enable the boxes for the permissions to the SAP Gateway for Microsoft service that your app for SharePoint will need.
17. Click SAVE at the bottom of the screen.

Configure the application to communicate with Azure AD

1. In Visual Studio, open the web.config file in the ASP.NET project.
2. In the <appSettings> section, the Office Developer Tools for Visual Studio have added elements for the ClientID and ClientSecret of the app for SharePoint. (These are used in the Azure ACS authorization system if the ASP.NET application accesses SharePoint. You can ignore them for the continuing example, but do not delete them. They are required in provider-hosted apps for SharePoint even if the app is not accessing SharePoint data. Their values will change each time you press F5 in Visual Studio.) Add the following two elements to the section. These are used by the application to authenticate to Azure AD. (Remember that applications, as well as users, are security principals in OAuth-based authentication and authorization systems.)
   <add key="ida:ClientID" value="" />
   <add key="ida:ClientKey" value="" />
   

3. Insert the client ID that you saved from your Azure AD directory in the earlier procedure as the value of the ida:ClientID key. Leave the casing and punctuation exactly as you copied it and be careful not to include a space character at the beginning or end of the value. For the ida:ClientKey key use the key that you saved from the directory. Again, be careful not to introduce any space characters or change the value in any way. The <appSettings> section should now look something like the following. (The ClientId value may have a GUID or an empty string.)
   <appSettings>
     <add key="ClientId" value="" />
     <add key="ClientSecret" value="LypZu2yVajlHfPLRn5J2hBrwCk5aBOHxE4PtKCjIQkk=" />
     <add key="ida:ClientID" value="4da99afe-08b5-4bce-bc66-5356482ec2df" />
     <add key="ida:ClientKey" value="URwh/oiPay/b5jJWYHgkVdoE/x7gq3zZdtcl/cG14ss=" />
   </appSettings>
   

   Note
   Your application is known to Azure AD by the “localhost” URL you used to register it. The client ID and client key are associated with that identity. When you are ready to stage your application to an Azure Web Site, you will re-register it with a new URL.

4. Still in the appSettings section, add an Authority key and set its value to the Office 365 domain (some_domain.onmicrosoft.com) of your organizational account. In the continuing example, the organizational account is Bob@<O365_domain>.onmicrosoft.com, so the authority is <O365_domain>.onmicrosoft.com.
   <add key="Authority" value="<O365_domain>.onmicrosoft.com" />
   

5. Still in the appSettings section, add an AppRedirectUrl key and set its value to the page that the user’s browser should be redirected to after the ASP.NET app has obtained an authorization code from Azure AD. Usually, this is the same page that the user was on when the call to Azure AD was made. In the continuing example, use the SSL URL value with “/Pages/Default.aspx” appended to it as shown below. (This is another value that you will change for staging.)
   Copy

   <add key="AppRedirectUrl" value="https://localhost:44322/Pages/Default.aspx" />
   

6. Still in the appSettings section, add a ResourceUrl key and set its value to the APP ID URI of SAP Gateway for Microsoft (not the APP ID URI of your ASP.NET application). Obtain this value from the SAP Gateway for Microsoft administrator. The following is an example.
   <add key="ResourceUrl" value="http://<SAP_gateway_domain>.cloudapp.net/" />
   

   The <appSettings> section should now look something like this:

   <appSettings>
     <add key="ClientId" value="06af1059-8916-4851-a271-2705e8cf53c6" />
     <add key="ClientSecret" value="LypZu2yVajlHfPLRn5J2hBrwCk5aBOHxE4PtKCjIQkk=" />
     <add key="ida:ClientID" value="4da99afe-08b5-4bce-bc66-5356482ec2df" />
     <add key="ida:ClientKey" value="URwh/oiPay/b5jJWYHgkVdoE/x7gq3zZdtcl/cG14ss=" />
     <add key="Authority" value="<O365_domain>.onmicrosoft.com" />
     <add key="AppRedirectUrl" value="https://localhost:44322/Pages/Default.aspx" />
     <add key="ResourceUrl" value="http://<SAP_gateway_domain>.cloudapp.net/" />
   </appSettings>
   

7. Save and close the web.config file.

   Tip
   Do not leave the web.config file open when you run the Visual Studio debugger (F5). The Office Developer Tools for Visual Studio change the ClientId value (not the ida:ClientID) every time you press F5. This requires you to respond to a prompt to reload the web.config file, if it is open, before debugging can execute.

Add a helper class to authenticate to Azure AD

1. Right-click the ASP.NET project and use the Visual Studio item adding process to add a new class file to the project named AADAuthHelper.cs.
2. Add the following using statements to the file.
   using Microsoft.IdentityModel.Clients.ActiveDirectory;
   using System.Configuration;
   using System.Web.UI;
   
   

3. Change the access keyword from public to internal and add the static keyword to the class declaration.
   internal static class AADAuthHelper
   

4. Add the following fields to the class. These fields store information that your ASP.NET application uses to get access tokens from AAD.
   private static readonly string _authority = ConfigurationManager.AppSettings["Authority"];
   private static readonly string _appRedirectUrl = ConfigurationManager.AppSettings["AppRedirectUrl"];
   private static readonly string _resourceUrl = ConfigurationManager.AppSettings["ResourceUrl"];     
           
   private static readonly ClientCredential _clientCredential = new ClientCredential(
                              ConfigurationManager.AppSettings["ida:ClientID"],
                              ConfigurationManager.AppSettings["ida:ClientKey"]);
   
   private static readonly AuthenticationContext _authenticationContext = 
               new AuthenticationContext("https://login.windows.net/common/" + 
                                         ConfigurationManager.AppSettings["Authority"]);
   

5. Add the following property to the class. This property holds the URL to the Azure AD login screen.
   private static string AuthorizeUrl
   {
       get
       {
           return string.Format("https://login.windows.net/{0}/oauth2/authorize?response_type=code&redirect_uri={1}&client_id={2}&state={3}",
               _authority,
               _appRedirectUrl,
               _clientCredential.OwnerId,
               Guid.NewGuid().ToString());
       }
   }
   
   

6. Add the following properties to the class. These cache the access and refresh tokens and check their validity.
   public static Tuple<string, DateTimeOffset> AccessToken
   {
       get {
   return HttpContext.Current.Session["AccessTokenWithExpireTime-" + _resourceUrl] 
          as Tuple<string, DateTimeOffset>;
       }
   
       set { HttpContext.Current.Session["AccessTokenWithExpireTime-" + _resourceUrl] = value; }
   }
   
   private static bool IsAccessTokenValid
   {
      get 
      { 
          return AccessToken != null &&
          !string.IsNullOrEmpty(AccessToken.Item1) &&
          AccessToken.Item2 > DateTimeOffset.UtcNow;
      }
   }
   
   private static string RefreshToken
   {
       get { return HttpContext.Current.Session["RefreshToken" + _resourceUrl] as string; }
       set { HttpContext.Current.Session["RefreshToken-" + _resourceUrl] = value; }
   }
   
   private static bool IsRefreshTokenValid
   {
       get { return !string.IsNullOrEmpty(RefreshToken); }
   }
   
   

7. Add the following methods to the class. These are used to check the validity of the authorization code and to obtain an access token from Azure AD by using either an authentication code or a refresh token.
   private static bool IsAuthorizationCodeNotNull(string authCode)
   {
       return !string.IsNullOrEmpty(authCode);
   }
   
   private static Tuple<Tuple<string,DateTimeOffset>,string> AcquireTokensUsingAuthCode(string authCode)
   {
       var authResult = _authenticationContext.AcquireTokenByAuthorizationCode(
                   authCode,
                   new Uri(_appRedirectUrl),
                   _clientCredential,
                   _resourceUrl);
   
       return new Tuple<Tuple<string, DateTimeOffset>, string>(
                   new Tuple<string, DateTimeOffset>(authResult.AccessToken, authResult.ExpiresOn), 
                   authResult.RefreshToken);
   }
   
   private static Tuple<string, DateTimeOffset> RenewAccessTokenUsingRefreshToken()
   {
       var authResult = _authenticationContext.AcquireTokenByRefreshToken(
                            RefreshToken,
                            _clientCredential.OwnerId,
                            _clientCredential,
                            _resourceUrl);
   
       return new Tuple<string, DateTimeOffset>(authResult.AccessToken, authResult.ExpiresOn);
   }
   
   

8. Add the following method to the class. It is called from the ASP.NET code behind to obtain a valid access token before a call is made to get SAP data via SAP Gateway for Microsoft.
   internal static void EnsureValidAccessToken(Page page)
   {
       if (IsAccessTokenValid) 
       {
           return;
       }
       else if (IsRefreshTokenValid) 
       {
           AccessToken = RenewAccessTokenUsingRefreshToken();
           return;
       }
       else if (IsAuthorizationCodeNotNull(page.Request.QueryString["code"]))
       {
           Tuple<Tuple<string, DateTimeOffset>, string> tokens = null;
           try
           {
               tokens = AcquireTokensUsingAuthCode(page.Request.QueryString["code"]);
           }
           catch 
           {
               page.Response.Redirect(AuthorizeUrl);
           }
           AccessToken = tokens.Item1;
           RefreshToken = tokens.Item2;
           return;
       }
       else
       {
           page.Response.Redirect(AuthorizeUrl);
       }
   }
   

Tip
The AADAuthHelper class has only minimal error handling. For a robust, production quality app for SharePoint, add more error handling as described in this MSDN node: Error Handling in OAuth 2.0.

Create data model classes

1. Create one or more classes to model the data that your app gets from SAP. In the continuing example, there is just one data model class. Right-click the ASP.NET project and use the Visual Studio item adding process to add a new class file to the project named Automobile.cs.
2. Add the following code to the body of the class:
   public string Price;
   public string Brand;
   public string Model;
   public int Year;
   public string Engine;
   public int MaxPower;
   public string BodyStyle;
   public string Transmission;
   

Add code behind to get data from SAP via the SAP Gateway for Microsoft

1. Open the Default.aspx.cs file and add the following using statements.
   using System.Net;
   using Newtonsoft.Json.Linq;
   

2. Add a const declaration to the Default class whose value is the base URL of the SAP OData endpoint that the app will be accessing. The following is an example:
   private const string SAP_ODATA_URL = @"https://<SAP_gateway_domain>.cloudapp.net:8081/perf/sap/opu/odata/sap/ZCAR_POC_SRV/";
   

3. The Office Developer Tools for Visual Studio have added a Page_PreInit method and a Page_Load method. Comment out the code inside the Page_Load method and comment out the whole Page_Init method. This code is not used in this sample. (If your app for SharePoint is going to access SharePoint, then you restore this code. See Optionally, add SharePoint access to the ASP.NET application.)
4. Add the following line to the top of the Page_Load method. This will ease the process of debugging because your ASP.NET application is communicating with SAP Gateway for Microsoft using SSL (HTTPS); but your “localhost:port” server is not configured to trust the certificate of SAP Gateway for Microsoft. Without this line of code, you would get an invalid certificate warning before Default.aspx will open. Some browsers allow you to click past this error, but some will not let you open Default.aspx at all.
   ServicePointManager.ServerCertificateValidationCallback = (s, cert, chain, errors) => true;
   

   Important
   Delete this line when you are ready to deploy the ASP.NET application to staging. See Modify the app and stage it to Azure and Office 365.

5. Add the following code to the Page_Load method. The string you pass to the GetSAPData method is an OData query.
   if (!IsPostBack)
   {
       GetSAPData("DataCollection?$top=3");
   }
   
   

6. Add the following method to the Default class. This method first ensures that the cache for the access token has a valid access token in it that has been obtained from Azure AD. It then creates an HTTP GET Request that includes the access token and sends it to the SAP OData endpoint. The result is returned as a JSON object that is converted to a .NET List object. Three properties of the items are used in an array that is bound to the DataListView.
   private void GetSAPData(string oDataQuery)
   {
       AADAuthHelper.EnsureValidAccessToken(this);
   
       using (WebClient client = new WebClient())
       {
           client.Headers[HttpRequestHeader.Accept] = "application/json";
           client.Headers[HttpRequestHeader.Authorization] = "Bearer " + AADAuthHelper.AccessToken.Item1;
           var jsonString = client.DownloadString(SAP_ODATA_URL + oDataQuery);
           var jsonValue = JObject.Parse(jsonString)["d"]["results"];
           var dataCol = jsonValue.ToObject<List<Automobile>>();
   
           var dataList = dataCol.Select((item) => {
               return item.Brand + " " + item.Model + " " + item.Price;
               }).ToArray();
   
           DataListView.DataSource = dataList;
           DataListView.DataBind();
       }
   }
   
   

Create the user interface

1. Open the Default.aspx file and add the following markup to the form of the page:
   <div>
     <h3>Data from SAP via SAP Gateway for Microsoft</h3>
   
     <asp:ListView runat="server" ID="DataListView">
       <ItemTemplate>
         <tr runat="server">
           <td runat="server">
             <asp:Label ID="DataLabel" runat="server"
               Text="<%# Container.DataItem.ToString()%>" /><br />
           </td>
         </tr>
       </ItemTemplate>
     </asp:ListView>
   </div>
   

2. Optionally, give the web page the “look ‘n’ feel” of a SharePoint page with the SharePoint Chrome Control and the host SharePoint website’s style sheet.

Test the app with F5 in Visual Studio

1. Press F5 in Visual Studio.
2. The first time that you use F5, you may be prompted to login to the Developer Site that you are using. Use the site administrator credentials. In the continuing example, it is Bob@<O365_domain>.onmicrosoft.com.
3. The first time that you use F5, you are prompted to grant permissions to the app. Click Trust It.
4. After a brief delay while the access token is being obtained, the Default.aspx page opens. Verify that the SAP data appears.

Optionally, add SharePoint access to the ASP.NET application

---

Of course, your app for SharePoint doesn’t have to expose only SAP data in a web page launched from SharePoint. It can also create, read, update, and delete (CRUD) SharePoint data. Your code behind can do this using either the SharePoint client object model (CSOM) or the REST APIs of SharePoint. The CSOM is deployed as a pair of assemblies that the Office Developer Tools for Visual Studio automatically included in the ASP.NET project and set to Copy Local in Visual Studio so that they are included in the ASP.NET application package. For information about using CSOM, start with How to: Complete basic operations using SharePoint 2013 client library code. For information about using the REST APIs, start with Understanding and Using the SharePoint 2013 REST Interface.Regardless, of whether you use CSOM or the REST APIs to access SharePoint, your ASP.NET application must get an access token to SharePoint, just as it does to SAP Gateway for Microsoft. See Understand authentication and authorization to SAP Gateway for Microsoft and SharePoint above. The procedure below provides some basic guidance about how to do this, but we recommend that you first read the following articles:

• How to: Create a basic provider-hosted app for SharePoint
• Authorization and authentication of apps for SharePoint 2013
• Three authorization systems for apps for SharePoint 2013
• Creating apps for SharePoint that use low-trust authorization
• Context Token OAuth flow for apps in SharePoint 2013

1. Open the Default.aspx.cs file and uncomment the Page_PreInit method. Also uncomment the code that the Office Developer Tools for Visual Studio added to the Page_Load method.
2. If your app for SharePoint is going to access SharePoint data, then you have to cache the SharePoint context token that is POSTed to the Default.aspx page when the app is launched in SharePoint. This is to ensure that the SharePoint context token is not lost when the browser is redirected following the Azure AD authentication. (You have several options for how to cache this context. See OAuth tokens.) The Office Developer Tools for Visual Studio add a SharePointContext.cs file to the ASP.NET project that does most of the work. To use the session cache, you simply add the following code inside the “if (!IsPostBack)” block before the code that calls out to SAP Gateway for Microsoft:
   if (HttpContext.Current.Session["SharePointContext"] == null) 
   {
        HttpContext.Current.Session["SharePointContext"]
           = SharePointContextProvider.Current.GetSharePointContext(Context);
   }
   

3. The SharePointContext.cs file makes calls to another file that the Office Developer Tools for Visual Studio added to the project: TokenHelper.cs. This file provides most of the code needed to obtain and use access tokens for SharePoint. However, it does not provide any code for renewing an expired access token or an expired refresh token. Nor does it contain any token caching code. For a production quality app for SharePoint, you need to add such code. The caching logic in the preceding step is an example. Your code should also cache the access token and reuse it until it expires. When the access token is expired, your code should use the refresh token to get a new access token. We recommend that you read OAuth tokens.
4. Add the data calls to SharePoint using either CSOM or REST. The following example is a modification of CSOM code that Office Developer Tools for Visual Studio adds to the Page_Load method. In this example, the code has been moved to a separate method and it begins by retrieving the cached context token.
   Copy

   private void GetSharePointTitle()
   {
       var spContext = HttpContext.Current.Session["SharePointContext"] as SharePointContext;
       using (var clientContext = spContext.CreateUserClientContextForSPHost())
       {
           clientContext.Load(clientContext.Web, web => web.Title);
           clientContext.ExecuteQuery();
           SharePointTitle.Text = "SharePoint web site title is: " + clientContext.Web.Title;
       }
   }
   

5. Add UI elements to render the SharePoint data. The following shows the HTML control that is referenced in the preceding method:
   <h3>SharePoint title</h3><asp:Label ID="SharePointTitle" runat="server"></asp:Label><br />
   

Note
While you are debugging the app for SharePoint, the Office Developer Tools for Visual Studio re-register it with Azure ACS each time you press F5 in Visual Studio. When you stage the app for SharePoint, you have to give it a long-term registration. See the section Modify the app and stage it to Azure and Office 365.

Modify the app and stage it to Azure and Office 365

---

When you have finished debugging the app for SharePoint using F5 in Visual Studio, you need to deploy the ASP.NET application to an actual Azure Web Site.

Create the Azure Web Site

1. In the Microsoft Azure portal, open WEB SITES on the left navigation bar.
2. Click NEW at the bottom of the page and on the NEW dialog select WEB SITE | QUICK CREATE.
3. Enter a domain name and click CREATE WEB SITE. Make a copy of the new site’s URL. It will have the form my_domain.azurewebsites.net.

Modify the code and markup in the application

1. In Visual Studio, remove the line ServicePointManager.ServerCertificateValidationCallback = (s, cert, chain, errors) => true; from the Default.aspx.cs file.
2. Open the web.config file of the ASP.NET project and change the domain part of the value of the AppRedirectUrl key in the appSettings section to the domain of the Azure Web Site. For example, change <add key=”AppRedirectUrl” value=”https://localhost:44322/Pages/Default.aspx&#8221; /> to <add key=”AppRedirectUrl” value=”https://my_domain.azurewebsites.net/Pages/Default.aspx&#8221; />.
3. Right-click the AppManifest.xml file in the app for SharePoint project and select View Code.
4. In the StartPage value, replace the string ~remoteAppUrl with the full domain of the Azure Web Site including the protocol; for example https://my_domain.azurewebsites.net. The entire StartPage value should now be: https://my_domain.azurewebsites.net/Pages/Default.aspx. (Usually, the StartPage value is exactly the same as the value of the AppRedirectUrl key in the web.config file.)

Modify the AAD registration and register the app with ACS

1. Login into Azure Management portal with your Azure administrator account.
2. Choose Active Directory on the left side.
3. Click on your directory.
4. Choose APPLICATIONS (on the top navigation bar).
5. Open the application you created. In the continuing example, it is ContosoAutomobileCollection.
6. For each of the following values, change the “localhost:port” part of the value to the domain of your new Azure Web Site:
   • SIGN-ON URL
   • APP ID URI
   • REPLY URL

   For example, if the APP ID URI is https://localhost:44304/ContosoAutomobileCollection, change it to https://<my_domain&gt;.azurewebsites.net/ContosoAutomobileCollection.

7. Click SAVE at the bottom of the screen.
8. Register the app with Azure ACS. This must be done even if the app does not access SharePoint and will not use tokens from ACS, because the same process also registers the app with the App Management Service of the Office 365 subscription, which is a requirement. You perform the registration on the AppRegNew.aspx page of any SharePoint website in the Office 365 subscription. For details, see Guidelines for registering apps for SharePoint 2013. As part of this process you will obtain a new client ID and client secret. Insert these values in the web.config for the ClientId (not ida:ClientID) and ClientSecret keys.

   Caution
   If for any reason you press F5 after making this change, the Office Developer Tools for Visual Studio will overwrite one or both of these values. For that reason, you should keep a record of the values obtained with AppRegNew.aspx and always verify that the values in the web.config are correct just before you publish the ASP.NET application.

Publish the ASP.NET application to Azure and install the app to SharePoint

1. There are several ways to publish an ASP.NET application to an Azure Web Site. For more information, see How to Deploy an Azure Web Site.
2. In Visual Studio, right-click the SharePoint app project and select Package. On the Publish your app page that opens, click Package the app. File explorer opens to the folder with the app package.
3. Login to Office 365 as a global administrator, and navigate to the organization app catalog site collection. (If there isn’t one, create it. See Use the App Catalog to make custom business apps available for your SharePoint Online environment.)
4. Upload the app package to the app catalog.
5. Navigate to the Site Contents page of any website in the subscription and click add an app.
6. On the Your Apps page, scroll to the Apps you can add section and click the icon for your app.
7. After the app has installed, click it’s icon on the Site Contents page to launch the app.

For more information about installing apps for SharePoint, see Deploying and installing apps for SharePoint: methods and options.

Deploying the app to production

---

When you have finished all testing you can deploy the app in production. This may require some changes.

1. If the production domain of the ASP.NET application is different from the staging domain, you will have to change AppRedirectUrl value in the web.config and the StartPage value in the AppManifest.xml file, and repackage the app for SharePoint. See the procedure Modify the code and markup in the application above.
2. The change in domain also requires that you edit the apps registration with AAD. See the procedure Modify the AAD registration and register the app with ACS above.
3. The change in domain also requires that you re-register the app with ACS (and the subscription’s App Management Service) as described in the same procedure. (There is no way to edit an app’s registration with ACS.) However, it is not necessary to generate a new client ID or client secret on the AppRegNew.aspx page. You can copy the original values from the ClientId (not ida:ClientID) and ClientSecret keys of the web.config into the AppRegNew form. If you do generate new ones, be sure to copy the new values to the keys in web.config.

How To : Automate a Test Case in Microsoft Test Manager & Setup Automated Build-Deploy-Test Workflows

To automate a test case, link it to a coded test method. You can link any unit test, coded UI test, or generic test to a test case. You’ll want to link a test method that performs the test described by the test case. Typically these are integration tests.

The results of automated and manual tests appear together. If the test cases are linked to backlog items, stories, or other requirements, you can review the test results by requirement.

Link test cases to test methods

You can make links one at a time, or you can generate test cases from an assembly of test classes.

Link a single test case to a test method

1. Using Visual Studio, create or choose a test method. It can be an ordinary test method, a coded UI test, ordered test, or a generic test method.

   Check the method into Team Foundation Server.

   Keep the solution open in Visual Studio.

2. Open the test case in Visual Studio.
   
3. Associate the test method with your test case.
   

   If you want to change or delete the association later, choose Remove Association.

We don’t recommend linking load tests or web tests to test cases.

Create test cases from an assembly of tests methods

1. Open a Developer Command Prompt, and change directory to the output director of your Visual Studio solution.

   cd MySolution\MyProject\bin\Debug

2. To import all the test methods from the solution:

   tcm testcase /collection: CollectionUrl /teamproject:MyProject /import /storage:MyAssembly.dll /category:”MyIntegrationTestCategory“

   The category parameter is optional but recommended. You only want to create test cases from integration or system tests, which you can mark by using the [TestCategory (“category”)] attribute.

3. In the Test hub in Team Web Access or in Microsoft Test Manager, use Add Existing to add the test cases to a test suite.

Ads by CeheuapMMeAd Options

Set Your Test Plan to Use Your Build

Provide the build location so that the test method can be found.

1. In Microsoft Test Manager, choose Testing Center, , Properties.
2. Under Builds, set Filter for builds. You can set the build definition and quality attribute of the builds you want to choose from.
3. Choose Modify to assign a build to the test plan. You can compare your current build with a build you plan to take. The associated items list shows the changes to work items between the builds. You can then assign the latest build to take and use for testing with this plan. For more information, see What development has been done since a previous build?.

I’m not using Team Foundation Build to build my application and tests. How can I run automated lab tests?

Create a build definition that contains just the location where your assemblies are shared. Then create a fake instance of this build from the developer command prompt:

TfsCreateBuild.exe /collection:http://tfsservername:8080/tfs/collectionname /project: projectname /builddefinition:”MyBuildDefinition” /buildnumber:”FakeBuild_1.0″

Specify the build definition in your test plan.

Create a Lab Environment and Settings to Run Your Tests

To run your automated tests tests using Microsoft Test Manager, you must use a lab environment. It must have roles for each of the client and server machines used in your tests. (If you’ve used lab environments for manual tests, notice that automated tests must have a machine for the client role.)

1. Create or choose either a standard lab environment or an SCVMM lab environment.

   If you create a new environment, choose a machine for each role.

   

   If you’re planning to run coded UI tests, configure it on the Advanced page of the wizard. This sets the test agent to run as a user. You have to supply a user name under which the agent will run.

   We recommend that you use a different user account than the lab service account used by the test controller.

   
2. Set the test plan to use your environment for automated tests.
   
3. If you want to collect more than the basic diagnostic data from the test machines, create a test settings file.
   

   In the test settings wizard, choose the data you want to collect for each machine.

   

Run the Automated Test

Start automated tests the same way you do manual tests.

In Microsoft Test Manager, choose Testing Center, . Then select a test suite or an individual test and choose .

If you want to run a test in a different environment or with different test settings, choose Run with Options.

If you want to run an automated test manually, choose Run with Options.

If you have multiple build configurations, the test assemblies to run the automated tests are searched for recursively from the root directory of the build drop folder. If it is important which assemblies are selected when you run your automated tests, you should use Run with options to specify the build configuration.

Ads by CeheuapMMeAd Options

View and Update the Test Results

1. In Microsoft Test Manager, choose Testing Center, , Analyze Test Runs.
2. Double-click a test run to open it and view the details. You can:
   • Update the title of the test run to reflect the outcome.
   • Choose Resolution to indicate a reason, if the test failed.
   • Add comments.
   • View the details of an individual test.
   • Create a bug.

Q: Can I generate the test method from a manual run of the test case?

Yes. Verifying Code by Using UI Automation (Various Blog Post can be found on my Blog about Coded UI Test Automation)

Q: I want my automated test to repeat with different data. Do I use the same test parameters that the manual version of the test case uses?

To make the automated test iterate over different data, write that into the code of the test method.

Test parameters are only used with the manual version of the test. They aren’t visible to the automated test code.

Automated build-deploy-test workflows

You can use a build-deploy-test on Team Foundation Server to deploy and test your application when you run a build. This lets you schedule and run the build, deployment, and testing of your application with one build process. Build-deploy-test work with Lab Management to deploy your applications to a lab environment and run tests on them as part of the build process.

If your lab environment is an SCVMM environment, you can also use workflows to create and restore snapshots that automatically create a clean environment before you run tests, and to the state of your environment when a test fails. This ensures that each test isn’t influenced by changes to the lab environment from previous test runs. In addition, it ensures that testers can accurately reproduce that state of a lab environment when they reproduce bugs.

Requirements

• Visual Studio Ultimate, Visual Studio Premium, Visual Studio Test Professional

You can use a build-deploy-test in the following scenarios:

Tip
Build, or Build and Test: If you are building your application in a drop folder without deploying it to a lab environment, then you can use the default build process template. For more information, see Use the Default Template for your build process. If you also want to test your application without deploying it, see Run tests in your build process

• Build, Deploy, and Test − Build your application, then deploy it and run tests on it in a lab environment. This workflow enables you to run a series of tests from a test plan, on a deployed application, as part of your build process. This scenario is common when running build verification tests.
• Deploy and Test − This scenario is similar to the “build, deploy, and test” scenario, except a new build isn’t created during the workflow. Instead, the workflow uses an existing build from a drop folder.
• Deploy Only – Deploy an existing build from a drop folder to a lab environment without running automated tests during the workflow. Once a build has passed your build verification tests, and is ready to be sent to a test team, you might want to send that build to the test team so they can run additional tests that aren’t part of your workflow. This scenario is common when running manual tests.
• Build and Deploy – This scenario is similar to the “deploy only” scenario, except a new build is created during the workflow.

A build-deploy-test workflow is a Windows Workflow file that defines how a build definition will run a build, deploy an application, and run tests. A build-deploy-test workflow is created in a build definition by choosing a build process template called the lab default template (LabDefaultTemplate.11.xaml), and configuring the settings.

You can also create a customized build process template for your workflow depending on your requirements. You configure your build definition after you set up your build machine, test machines, and lab environments.

The deployment settings in a -deploy-test workflow define how an application is deployed by specifying the deployment scripts to run on in your lab environment. You can specify a lab management role to run each deployment script on, or you can specify a machine in your lab environment.

Creating deployment scripts is a major part of setting up -deploy-test workflows. Deployment scripts copy files from your build to your lab environment, and then run your installation packages.

The following diagram describes how a build is deployed by a build-deploy-test workflow:

The following steps are displayed in the diagram above.

1. The build-deploy-test workflow starts a build, and then gets the deployment scripts.
2. The build definition copies the build files to the drop location.
3. The workflow runs each deployment script in the working directory of the specific machine or machine role that the script is assigned to.
4. Each deployment script retrieves build files from the drop location.
5. Each deployment script copies or installs the specified build files onto machines in the lab environment.

How To : Use Azure BizTalk Services to Integrate with an On-Premises SAP Server

Microsoft Azure BizTalk Services provides a rich set of integration capabilities enabling organizations to create hybrid solutions such that their customer or partner facing applications are hosted on Azure, while the data related to customers or partners is stored on-premises using LOB applications.

To demonstrate how to integrate applications with an on-premises LOB application using BizTalk Services, let us consider a scenario involving two business partners, Fabrikam and Contoso.

Business Scenario

Contoso sends a purchase order (PO) message to Fabrikam in an X12 Electronic Data Interchange (EDI) format using the PO (X12 850) schema. Fabrikam (that uses an SAP Server to manage partner data), accepts PO from its partners using the ORDERS05 IDOCS.

To enable Contoso to send a PO directly to Fabrikam’s on-premises SAP Server, Fabrikam decides to use Azure’s integration offering, BizTalk Services, to set up a hybrid integration scenario where the integration layer is hosted on and the SAP Server is within the organization’s firewall. Fabrikam uses BizTalk Services in the following ways to enable this hybrid integration scenario:

1. Fabrikam uses Microsoft Azure BizTalk Services SDK to create a BizTalk Service project. The project includes a XML One-Way Bridge to send messages to a relay endpoint, which in turns sends the message to the on-premise SAP system.
2. Fabrikam uses the BizTalk Adapter Service component available with BizTalk Services to expose the Send operation on ORDERS05 IDOC as an operation using Service Bus relay endpoint. The XML One-Way Bridge sends messages to this relay endpoint. Fabrikam also creates the schema for Send operation using BizTalk Adapter Service and includes the schema as part of the BizTalk Service project.

   Note
   A Send operation on an IDOC is an operation that is exposed by the BizTalk Adapter Pack on any IDOC to send the IDOC to the SAP Server. BizTalk Adapter Service uses BizTalk Adapter Pack to connect to an SAP Server.

3. Fabrikam uses the Transform component available with BizTalk Services to create a map to transform the PO message in X12 format into the schema required by the SAP Server to invoke the Send operation on the ORDERS05 IDOC.
4. Fabrikam uses the Microsoft Azure BizTalk Services Portal available with BizTalk Services to create and deploy an EDI agreement under the BizTalk Services subscription that processes the X12 850 PO message. As part of the message processing, the agreement also does the following:
   1. Receives an X12 850 PO message over FTP.
   2. Transforms the X12 PO message into the schema required by the SAP Server using the transform created earlier.
   3. Routes the transformed message to the XML One-Way Bridge that eventually routes the message to a relay endpoint created for sending a PO message to an SAP Server. Fabrikam earlier exposed (as explained in bullet 1 above) the Send operation on ORDERS05 IDOC as a relay endpoint, to enable partners to send PO messages using BizTalk Adapter Service.

Once this is set up, Contoso drops an X12 850 PO message to the FTP location. This message is consumed by the EDI receive pipeline, which processes the message, transforms it to an ORDERS05 IDOC, and routes it to the intermediary XML bridge. The bridge then routes the message to the relay endpoint on Service Bus, which is then sent to the on-premises SAP Server. The following illustration represents the same scenario.

How to Use This Article

 

This tutorial is written around a sample, SAPIntegration, which is available as part of the download (SAPIntegration.zip) from the MSDN Code Gallery. You could either use the SAPIntegration sample and go through this tutorial to understand how the sample was built or just use this tutorial to create your own application.

This tutorial is targeted towards the second approach so that you get to understand how this application was built. Also, to be consistent with the sample, the names of artifacts (e.g. schemas, transforms, etc.) used in this tutorial are same as that in the sample.

The sample available from the MSDN code gallery contains only half the solution, which can be developed at design-time on your computer. The sample cannot include the configuration that you must do on the BizTalk Services Portal on Azure.

For that, you must follow the steps in this tutorial to set up your EDI bridge. Even though Microsoft recommends that you follow the tutorial to best understand the concepts and procedures, if you really wish to use the sample, this is what you should do:

• Download the SAPIntegration.zip package, extract the SAPIntegration sample and make relevant changes like providing your service namespace, issuer name, issuer key, SAP Server details, etc. After changing the sample, deploy the application to get the endpoint URL at which the XML One-Way Bridge is deployed.
• Use the BizTalk Services Portal to configure the Receive settings as described at Step 5: Create and Deploy the EDI Receive Pipeline and follow the procedures to route messages from the EDI Receive bridge to the XML One-Way Bridge you already deployed.
• Drop a test message at the FTP location configured as part of the agreement and verify that the application works as expected.
  • If the message is successfully processed, it will be routed to the SAP Server and you can verify the ORDERS IDOC using the SAP GUI.
  • If the EDI agreement fails to process the message, the failure/error messages are routed to a relay endpoint on Service Bus. To receive such messages, you must set up a relay receiver service that receives any message that comes to that specific relay endpoint. More details on why you need this service and how to use it are available at Step 6: Test the Solution.

Steps in the Solution :

 

• Step 1: Set up Your Computer
• Step 2: Expose a Relay Endpoint to Invoke Operations on ORDERS05 IDOC
• Step 3: Transform the X12 850 PO Message to the ORDERS05 Message
• Step 4: Create and Deploy the XML Bridge
• Step 5: Create and Deploy the EDI Receive Pipeline
• Step 6: Test the Solution

Step 1: Set up Your Computer

This topic provides you with instruction and pointers to set up your computer on which you will perform the steps to set up the hybrid integration scenario described in Tutorial: Using Azure BizTalk Services to Integrate with an On-Premises SAP Server. You must do the following to set up your computer:

• Install Microsoft Azure BizTalk Services SDK. You can download the installer from http://go.microsoft.com/fwlink/?LinkId=235057. You use this SDK to configure and deploy the XML One-Way Bridge that sits between the EDI agreement and the relay endpoint.
• Install BizTalk Adapter Service. You use this to expose the Send operation on an IDOC as a relay endpoint on Service Bus.You can download the installer from http://go.microsoft.com/fwlink/?LinkId=235057. Refer to the BizTalk Services installation guide at http://go.microsoft.com/fwlink/?LinkId=237092 to install the software prerequisites for BizTalk Services SDK and BizTalk Adapter Service.
• Install the WCF LOB Adapter SDK. This is required for installing the Adapter Pack on the computer.
• Install the Adapter Pack. This contains the SAP adapter that is required to establish connectivity to an SAP Server and for exposing SAP artifacts as operations.
• Install the SAP client libraries. The SAP adapter needs these libraries to connect to an SAP Server. For information on where to install the SAP client libraries from, refer to the Adapter Pack installation guide (BizTalkAdapterPack_InstallationGuide.htm) at http://go.microsoft.com/fwlink/?LinkId=240161.
• Download and extract the EDI message schemas (MicrosoftEdiXSDTemplates.zip) available at http://go.microsoft.com/fwlink/?LinkId=235057. This contains the X12 850 Purchase Order message schema that is required for the business scenario we use for this article.

After you have finished installing and downloading these components, you are ready to start setting up the business scenario.

Step 2: Expose a Relay Endpoint to Invoke Operations on ORDERS05 IDOC

This topic has not yet been rated – Rate this topic

Updated: November 21, 2013

There are two main steps required to expose an SAP artifact as an operation that can be invoked by sending a message over Service Bus – create an LOB Target and an LOB Relay.

• An LOB Target defines how an Azure application communicates to the Line-of-Business (LOB) system. The LOB Target controls the LOB system connection URI, the operation to perform, and the connection credentials.
• An LOB Relay is a WCF service running within an organizations firewall and listens to a relay endpoint on the Service Bus. As the name suggests, the LOB Relay acts as a relay between the Service Bus relay endpoint and the LOB system. It receives the message at the Service Bus relay endpoint and passes it on to the relevant LOB system using the LOB Target configuration.

For more information, see BizTalk Adapter Service Architecture. In this topic, we will create an LOB Target and an LOB Relay to expose the Send operation on the ORDERS05 IDOC.

To create an LOB Target and LOB Relay

1. Open Visual Studio (as an administrator), create a new BizTalk Service project, and name it SAPIntegration.
2. You first start with adding a BizTalk Adapter Service server. This is the server where you installed the Runtime component of BizTalk Adapter Service. To add a BizTalk Adapter Service server, from the Server Explorer in Visual Studio, right-click BizTalk Adapter Services, and select Add BizTalk Adapter Service. In the Add BizTalk Adapter Service dialog box, enter the URL of the WCF service that monitors that Service Bus relay service, and then click OK.

   Because you have all the components of BizTalk Adapter Service installed on the same computer, the URL for that service will be http://localhost:8080/BAService/ManagementService.svc/.

   Note
   If you had installed BizTalk Adapter Service Runtime component on a separate computer, you would have replaced ‘localhost’ in the above URL with the name of that computer.

3. In this tutorial we are creating an application to integrate with SAP, so we must add an SAP target. Expand the newly added server, expand LOB Types, right-click SAP, and select Add SAP Target.

   The Add a Target wizard starts. Perform the following steps to create an LOB Target.

   1. Read the information on the Before You Begin page, and then click Next.
   2. On the Connection Parameters page, specify the details for the SAP Server to connect to and the credentials to use for the connection. Click Next.
   3. On the Operations page, expand the ORDERSO5 IDOC category (under \IDOC\ORDERS\). There are several versions of the IDOC available. For this tutorial, we’ll select ORDERS05.V3(700). Expand this IDOC, select Send, and then click the right arrow to add it to the Selected Operations box.

      Click Next.

   4. In the Runtime Security page, specify the security mechanism to be used by the LOB Server to authenticate the target resource when a message arrives from a client. For this tutorial, select Fixed Username and specify the credentials to connect to the SAP server.
   5. On the Deployment page, you create an LOB Relay and an LOB Target to provide connectivity to your on-premise LOB applications from the cloud.

      Select the Create new option to create a new relay and provide the following values:

      Name	Description
      Namespace	Specify the Service Bus namespace on which the LOB relay endpoint is created.
      Issuer name	Specify the issuer name for the Service Bus namespace
      Issuer secret	Specify the issuer secret for the Service Bus namespace
      Relay path	Specify a name for the relay. For this tutorial, enter sapintegration01.
      Target sub-path	Enter a sub-path to make this target unique. For this tutorial, enter orders.

      The Target runtime URL read-only property displays the URL where the relay is deployed on Service Bus. This is the path where you could send a message to be inserted into the on-premises SAP Server. In our scenario, this is where the bridge sends the message.

      Click Next.

   6. On the Summary page, review the values you specified in the previous steps, and then click Create.
   7. When the wizard completes, click Finish.

      In Visual Studio Server Explorer, you now have an entry under the SAP node. This represents the relay endpoint created in Service Bus to relay PO messages coming from the cloud to the on-premises SAP system.

To add schemas

1. After adding the relay endpoint to an SAP system, you must add schemas that to send ORDERS05 PO messages to the SAP server. To add the schemas, right-click the relay endpoint and select Add schemas to SAPIntegration. In the dialog box, do the following:
   • Enter a filename prefix that will be included in the name of each schema file that is generated. For this tutorial, specify this as SAPIntegration_.
   • Enter a folder name that will be added to your solution under which all the schemas will be added. For this tutorial, specify the folder name as LOB Schemas.
   • Enter the credentials to connect to an SAP system.

   Click OK. The schemas are added to the project under an LOB Schemas folder.

To use the LOB Target

1. Right-click anywhere on the BizTalk Service project design surface, select Properties and update the BizTalk Service URL property to include your BizTalk Services name. This is the name that you provided in Azure Management Portal while provisioning the BizTalk Services.
2. Set the security property for the relay endpoint.
   1. Right-click the LOB Target in Server Explorer and select Properties.
   2. In the Properties grid, click the ellipsis (…) against the Runtime Security property.
   3. In the Edit Security dialog box, select Fixed Username and specify username and password to connect to the SAP Server.
   4. Click OK.
3. Drag and drop the LOB Target onto the design surface. Note the Entity Name property of the LOB Target. The default value is Relay-Path_target-sub-path. If using the examples above, it will be sapintegration01_orders.
4. Open the .config file for the LOB Target, which typically has the naming convention as YourRelayPath_target-sub-path.config. Specify the Service Bus issuer name and issuer secret, as shown below:
     <sharedSecret issuerName="owner" issuerSecret="issuer_secret" />
   
   

   Save changes to the config file.

 

Step 3: Transform the X12 850 PO Message to the ORDERS05 Message

Both the X12 850 schemas and ORDERS05 schemas are pretty complex and require functional expertise in the respective domains to understand and create maps between the two schemas.

While you already generated the schema for ORDERS05 IDOC, you can get the schema for X12 PO message (X12_00401_850.xsd) from the MicrosoftEdiXSDTemplates.zip that you must have downloaded and extracted before. You must add the X12_00401_850.xsd schema as well to the SAPIntegration project.

Creating a transform between the X12 850 PO and ORDERS05 PO requires functional domain knowledge of both the X12 schema and the ORDERS05 schema.

Only then one can identify which field in the X12 schema maps to which field in the ORDERS05 schema. In this tutorial, we do not get into such details and instead use an existing transform (AzureTransformations.trfm) between these two schemas. This transform is available as part of the SAPIntegration project that you can download from the MSDN Code Gallery.

To include the transform in the BizTalk Service project, right-click the project name, click Add, click Existing Items, and then navigate to the location where you downloaded the SAPIntegration sample from the MSDN Code Gallery. Select the AzureTransformations.trfm and then click Add.

Step 4: Create and Deploy the XML Bridge

In this topic, you create an XML One-Way Bridge that will act as a connector between the EDI Receive bridge and the relay endpoint for the ORDERS05 IDOC in SAP. After configuring the bridge, you connect it to the SAP relay endpoint, and then deploy the solution.

To configure the XML Bridge

1. In the SAPIntegration project, from the Solution Explorer, double-click the MessageFlowItinerary.bcs file to open the bridge configuration surface.
2. Right-click anywhere on the BizTalk Service project design surface, select Properties, and update the BizTalk Service URL property to include your BizTalk Services name. This is the name that you provided in Azure Management Portal while provisioning the BizTalk Services.
3. From the Toolbox, drag and drop the XML One-Way Bridge component to the bridge design surface.
4. Right-click the XML One-Way Bridge, select Properties, and change the value for Entity Name and Relative Address properties to B2BConnector. As a result, the complete endpoint URL where the bridge is deployed, which is shown in the Runtime Address property, will resemble https://<mybiztalkservicename>.biztalk.windows.net/default/B2BConnector. This is where the EDI Receive bridge sends the ORDERS05 PO message.
5. Double-click the XML One-Way Bridge to open the Bridge Configuration design surface. Because this bridge only routes the message from the EDI Receive bridge to the relay endpoint, there’s not much configuration required for each stage in the bridge stage other than specifying the message types of the message that this bridge routes. To specify the message type, on the XML One-Way Bridge design surface, within the Message Types box, click the add icon [ ] to open the Message Type Picker dialog box.
6. In the Message Type Picker dialog box, from the Available message types box, select the schema for the request message and then click the right arrow icon [ ], and then click OK. For this tutorial, select the Send schema (http://Microsoft.LobServices.Sap/2007/03/Idoc/3/ORDERS05//700/Send). The selected schema should now be listed under the Request Message Type box.
7. Save the bridge configuration.

To connect the bridge to the relay endpoint

1. In the SAPIntegration project, from the Toolbox, select the Connection component, and connect the XML One-Way Bridge component with the SAP relay endpoint you already added in Step 2: Expose a Relay Endpoint to Invoke Operations on ORDERS05 IDOC.
2. Set the filter condition on the connection. The routing condition for this scenario is to route all messages to the LOB Target. To do so, select the connecting line, and from the Properties grid, click the ellipsis (…) against the Filter Condition property, and then select Match All. This ensures that all messages that come to the bridge are routed to the relay endpoint.
3. Set the Route Action property on the connection. Before you set the route action, we must understand why it is required. The message sent from the EDI receive bridge to the relay endpoint must have the Action SOAP header set on it. This header defines what operation must be performed on the SAP system. The message that comes from the EDI receive pipeline does not have this header set. Hence, in this intermediary XML bridge, you set the route action on the message before it is sent the relay endpoint. As part of the route action, you add the required header on the message. Perform the following steps to set the route action.
   1. Find out the value that will be set for the Action SOAP header message. To do so, right-click the SAP relay endpoint from the Server explorer, and from the Properties grid, expand Operations, and copy the value. For this tutorial, the value is http://Microsoft.LobServices.Sap/2007/03/Idoc/3/ORDERS05//700/Send.

      

   2. Go back to the bridge configuration surface, select the connection between the bridge and the SAP relay, and from the Properties grid, click the ellipsis (…) against the Route Action property. In the Route Actions dialog box, click Add to open the Add Route Action dialog box. In the Add Route Action dialog box, do the following:
      • Under Property (Read From) section, select Expression and specify the value that you copied earlier.

        Important
        Make sure you specify the value for Expression within single quotes.

      • Under Destination (Write-To) section, set the Type to SOAP and the Identifier to Action.

        

      • Click OK in the Add Route Action dialog box to add the route action. Click OK in the Route Actions dialog box and then click Save to save changes to an Enterprise Application Integration project.
4. Save the project. The final bridge configuration resembles the following:

   

To deploy the solution

1. In Visual Studio, right click the SAPIntegration solution, and then click Build Solution.
2. Once the build succeeds, right click the SAPIntegration solution, and then click Deploy Solution.
3. In the deployment window, the Deployment Endpoint is a read-only property and the value is derived from the BizTalk Service URL/Namespace set in the message flow surface. However, you must provide the ACS Namespace for BizTalk Services, Issuer Name, and Shared Secret.
4. Click Deploy. The Visual Studio Output pane displays the deployment progress and result. The URL where the bridge is deployed is also displayed in the Output pane. For this tutorial, the bridge is deployed at http://<mybiztalkservicename>.biztalk.windows.net/default/B2BConnector.

 

Name(required)

Email(required)

Agency / Company(required)

Job Spec(required)

Position

Company Position is at

Submit

Δ

 

How To : Use a Site mailbox to collaborate with your team

Share documents with others

Every team has documents of some kind that need to be stored somewhere, and usually need to be shared with others. If you store your team’s documents on your SharePoint site, you can easily leverage the Site Mailbox app to share those documents with those who have site access.

 Important    When users view a site mailbox in Outlook, they will see a list of all the documents in that site’s document libraries. Site mailboxes present the same list of documents to all users, so some users may see documents they do not have access to open.

If you’re using Exchange, your documents will also appear in a folder in Outlook, making it even easier to forward documents to others.

Organizations, and teams within organizations, often have several different email threads going in all directions at one time. It’s easy for lines to cross, information to get lost or overlooked, and for communication to break down. Site mailboxes enable you to store team or project-related email in one place, so that everyone on the team can see all communication.

On the Quick Launch, click Mailbox.

The site mailbox opens as a second, separate inbox and folder structure, next to your personal email account. Mail sent to and from the site mailbox account will be shared between all those who have Contributor permissions on the SharePoint site.

 Tip    Did you know you can also use a site mailbox to collaborate on documents?

Add a site mailbox as a mail recipient

By including the site mailbox on an important email thread, you ensure that a copy of the information in that thread is stored in a location that can be accessed by anyone on the team.

Simply add the site mailbox in the To, CC, or BCC line of an email message.

You could even consider adding the site mailbox email address to any team contact groups or distribution lists. That way, relevant email automatically gets stored in the team’s site mailbox.

Send email from the site mailbox

When you write and send email from the site mailbox, it will look as though it came from you.

Because everyone with Contributor permissions on a site can access the site mailbox, several people can work together to draft an email message.

To compose a message, simply click New Mail.

This will open a new message in your site mailbox.

When should I choose to create a mail app versus an add-in for Outlook?

Rate This

angelgolfer

Mon, Dec 10 2012 4:55 PM

• 1

Some of you may or may not be aware that alongside with the legacy COM-based Office client object models, Office 2013 supports a new apps for Office developer platform. This blog post is intended to help new and existing Office developers understand the main differences between the COM-based object models and the apps for Office platform. In particular, this post focuses on Outlook, suggests why you should consider developing solutions as mail apps, and identifies those exceptional scenarios where add-ins may still be the more appropriate choice.

Contents:

An introduction to the apps for Office platform

Architectural differences between add-in model and apps for Office platform

Main features available to mail apps

Major objects for mail apps

Reasons to create mail apps instead of add-ins for Outlook

Reasons to choose add-ins

Conclusion

Further references

An introduction to the apps for Office platform

The apps for Office platform includes a JavaScript API for Office and a schema for apps for Office manifests. You can use this platform to extend web services and content into the context of rich and web clients of Office. An app for Office is a webpage that is developed using common web technologies, hosted inside an Office client application (such as Outlook) on-premises or in the cloud. Of the three types of apps for Office, the type that Outlook supports is called mail apps. While you use the legacy APIs—the object model, PIA, and MAPI—to automate Outlook at an application level, you can use the JavaScript API for Office in a mail app to interact at an item level with the content and properties of an email message, meeting request, or appointment. You can publish mail apps in the Office Store or in an internal Exchange catalog. End users and administrators can install mail apps for an Exchange 2013 mailbox, and use mail apps in the Outlook rich client as well as Outlook Web App. As a developer, you can choose to make your mail app available for end users on only the desktop, or also on the tablet or smart phone. You can find more information about the apps for Office platform by starting here: Overview of apps for Office.

Architectural differences between add-in model and apps for Office platform

Add-in model

The Office add-in model offers individual object models for most of the Office rich clients. Each object model is intended to automate the corresponding Office client, and allows an add-in to integrate closely with the behavior of that client. The same add-in can integrate with one or multiple Office applications, such as Outlook, Word, and Excel, by calling into each of the Outlook, Word, and Excel object models. Figure 1 describes a few examples of 1:1 relationships between an Office rich client and its object model.

Figure 1. The legacy Office development architecture is composed of individual client object models.

 

Apps for Office platform

The apps for Office platform includes an apps for Office schema. Using this schema, each app specifies a manifest that describes the permissions it requests, its requirements for its host applications (for example, a mail app requires the host to support the mailbox capability), its support for the default and any extra locales, display details for one or more form factors, and activation rules for a mail app to be available in the app bar.

In addition to the schema, the apps for Office platform includes the JavaScript API for Office. This API spans across all supporting Office clients and allows apps to move toward a single code base. Rather than automating or extending a particular Office client at the application level, the apps for Office platform allows apps to connect to services and extend them into the context of a document, message, or appointment item in a rich or web client. Figure 2 shows Office applications with their rich and web clients sharing a common app platform.

Figure 2. The apps for Office development architecture is composed of a common platform and individual object models.

 

One main difference of note is that the object models were designed to integrate tightly with the corresponding Office client applications. However, this tight integration has a side effect of requiring an add-in to run in the same process as the rich client. The reliability and performance of an add-in often affects the perceived performance of the rich client. Unlike client add-ins, an app for Office doesn’t integrate as tightly with the host application, does not share the same process as the rich client, and instead runs in its own isolated runtime environment. This environment offers a privacy and permission model that allows users and IT administrators to monitor their ecosystem of apps and enjoy enhanced security.

Main features available to mail apps

Contextual activation: Mail app activation is contextual, based on the app’s activation rules and current circumstances, including the item that is currently displayed in the Reading Pane or inspector. A mail app is activated and becomes available to end users when such circumstances satisfy the activation rules in the app manifest.

Matching known entities or regular expression: A mail app can specify certain entities (such as a phone number or address) or regular expressions in its activation rules. If a match for entities or regular expressions occurs in the item’s subject or body, the mail app can access the match for further processing.

Roaming settings: A mail app can save data that is specific to Outlook and the user’s Exchange mailbox for access in a subsequent Outlook session.

Accessing item properties: A mail app can access built-in properties of the current item, such as the sender, recipients, and subject of a message, or the location, start, end, organizer, and attendees of a meeting request.

Creating item-level custom properties: A mail app can save item-specific data in the user’s Exchange mailbox for access in a subsequent Outlook session.

Accessing user profile: A mail app can access the display name, email address, and time zone in the user’s profile.

Authentication by identity tokens: A mail app can authenticate a user by using a token that identifies the user’s email account on an Exchange Server.

Using Exchange Web Services: A mail app can perform more complex operations or get further data about an item through Exchange Web Services.

Permissions model and governance: Mail apps support a three-tier permissions model. This model provides the basis for privacy and security for end users of mail apps.

Major objects for mail apps

For mail apps, you can look at the JavaScript API for Office object model in three layers:

1. In the first layer, there are a few objects shared by all three types of apps for Office: Office, Context, and AsyncResult.
2. The second layer in the API that is applicable and specific to mail apps includes the Mailbox, Item, and UserProfile objects, which support accessing information about the user and the item currently selected in the user’s mailbox.
3. The third layer describes the data-level support for mail apps:
   1. There are CustomProperties and RoamingSettings that support persisting properties set up by the mail app for the selected item and for the user’s mailbox, respectively.
   2. There are the supported item objects, Appointment and Message, that inherit from Item, and the MeetingRequest object that inherits from Message. These objects represent the types of Outlook items that support mail apps: calendar items of appointments and meetings, and message items such as email messages, meeting requests, responses, and cancellations.
   3. Then there are the item-level properties (such as Appointment.subject) as well as objects and properties that support certain known Entities objects (for example Contact, MeetingSuggestion, PhoneNumber, and TaskSuggestion).

Figure 3 shows the major objects: Mailbox, Item, UserProfile, Appointment, Message, Entities, and their members.

Figure 3. Major objects and their members used by mail apps in the JavaScript API for Office.

Figure 4 shows all of the objects and enumerations in the JavaScript API for Office that pertain to mail apps.

Figure 4. All objects for mail apps in the JavaScript API for Office.

Figure 5 is a thumbnail of a diagram with all the objects and members that mail apps use. Zoom into the diagram at http://go.microsoft.com/fwlink/?LinkId=317271.

Figure 5. All objects and members used by mail apps in the JavaScript API for Office.

The following are common reasons why mail apps are a better choice for developers than add-ins:

• You can use existing knowledge of and the benefits of web technologies such as HTML, JavaScript, and CSS. For power users and new developers, XML, HTML, and JavaScript require less significant ramp-up time than COM-based APIs such as the Outlook object      model.
• You can use a simple web deployment model to update your mail app (including the web services that the app uses) on your web server without any complex installation on the Outlook client. In fact, any updates to the mail app, with the exception of the app manifest, do not require any updating on the Office client. You can update the code or user interface of the mail app conveniently just on the web server. This presents a significant advantage over the administrative overhead involved in updating add-ins.
• You can use a common web development platform for mail apps that can roam across the Outlook rich client and Outlook Web App on the desktop, tablet, and smartphone. On the other hand, add-ins use the object model for the Outlook rich client and, hence, can run on only that rich client on a desktop form factor.
• You can enjoy rapid turnaround of building and releasing apps via the Office Store.
• Because of the three-tier permissions model, users and administrators can appreciate better security and privacy in mail apps than add-ins, which have full access to the content of each account in the user’s profile. This, in turn, encourages user consumption of apps.
• Depending on your scenarios, there are features unique to mail apps that you can take advantage of and that are not supported by add-ins:
  • You can specify a mail app to activate only for certain contexts (for example, Outlook displays the app in the app bar only if the message class of the user-selected appointment is IPM.Appointment.Contoso, or if the body of an email contains a package       tracking number or a customer identifier).
  • You can activate a mail app if the selected message contains some known entities, such as an address, contact, email address, meeting suggestion, or task suggestion.
  • You can take advantage of authentication by identity tokens and of Exchange Web Services.

Reasons to choose add-ins

The following features are unique to add-ins and may make them a more appropriate choice than mail apps in some circumstances:

• You can use add-ins to extend or automate Outlook at an application-level, because the object model and PIA have extensive integration with Outlook features (such as all Outlook item types, user interface, sessions, and rules). At the item-level, add-ins can interact with an item in read or compose mode. With mail apps, you cannot automate Outlook at the application level, and you can extend Outlook’s functionality in the context of only the read-mode of the supported items (messages and appointments) in the user’s mailbox.
• You can specify custom business logic for a new item type.
• You can modify and add custom commands in the ribbon and Backstage view.
• You can display a custom form page or form region.
• You can detect events such as sending an item or modifying properties of an item.
• You can use add-ins on Outlook 2013 and Exchange Server 2013, as well as earlier versions of Outlook and Exchange. On the other hand, mail apps work with Outlook and Exchange starting in Outlook 2013 and Exchange Server 2013, but not earlier versions.

Conclusion

When you are considering creating a solution for Outlook, first verify whether the supported major features and objects of the apps for Office platform meet your needs. Develop your solution as a mail app, if possible, to take advantage of the platform’s support across Outlook clients over the desktop, tablet, and smartphone form factors. Note that there are still some circumstances where add-ins are more appropriate, and you should prioritize the goals of your solution before making a decision.

Further references

Apps for Office and mail apps

Build apps for Office

Mail apps for Outlook

JavaScript API for Office

Schema reference for apps for Office manifests

Legacy Outlook object model and APIs

Welcome to the Outlook 2013 developer reference

Outlook 2013 MAPI Reference

What’s new for Outlook 2013 developers

Welcome to the Outlook 2010 Primary Interop Assembly Reference

How To : Customize the Duet Workflow Task form in InfoPath 2013

Contents

• Introduction
• Displaying the SAP business properties
• Adding and deleting controls on the form
• Adding heading images to the form and applying a theme

Introduction

After a task site is published through SharePoint Designer, the task form ApprovalProcess.xsn is generated. The form has a default layout. But we may also want to display the SAP business properties, add some more controls relevant to the use of the form, or delete some irrelevant controls. We may also want to give a nice look and feel to the form. We can do these customizations easily with the help of InfoPath 2013.

Scenario

We have published a task site of the task type TestTask using SharePoint Designer 2013. The task form has the default layout shown below. We want to customize the form to include a SAP business property, add a control, remove a control, add a heading image, and apply a theme.

Figure 1. TestTask task form with default layout

Displaying the SAP business properties

Prerequisite: We can display the SAP business properties in the workflow task form provided that we have included the properties in the Extended Business Properties text box while creating the task site.

Steps:

1. In SharePoint Designer, click ApprovalProcess.xsn.

Figure 2. ApprovalProcess.xsn in SharePoint Designer

InfoPath Designer opens with an auto-generated layout of the form.

Figure 3. InfoPath Designer with auto-generated layout of the TestTask form

2. Insert a new row, wherever you want, for the business property LeaveDaysUsedTillToday that you want to display in the form.

a. In the first column, enter the field name as you want to see it displayed in the form, for example,Leaves Used Till Today.

Figure 4. Entering field name in the first column

b. In the second column, we need to get the value for the business property LeavesUsedTillTodayfrom the Workflow Business Document Library. Thus, we need to create a secondary data connection with the Workflow Business Document Library.

3. Create a secondary data connection with the Workflow Business Document Library as follows: 

a. Under Actions, click Manage Data Connections.

Figure 5. Clicking Manage Data Connections in InfoPath

The Data Connections dialog box appears.

Figure 6. Data Connections dialog box

b. In the Data Connections dialog box, select Context  from the list of Data Connections for the form template, and click Add. The Data Connection Wizard starts.

Figure 7. Data Connection Wizard

c. Click Next without changing any settings. The wizard now asks for the source of data. SelectSharePoint library or list as the source of data.

Figure 8. Selecting SharePoint library or list in the Data Connection Wizard

d. Click Next. The wizard now prompts you to enter the location of the SharePoint site.

e. Enter the URL of the task site, and click Next.

Figure 9. Entering task site location in the Data Connection Wizard

f. Select the Workflow Business Data Document Library for the data connection, and click Next.

Figure 10. Selecting Workflow Business Data Document Library for the data connection

g. Select the Title and LeavesUsedTillToday fields, and click Next. The Title field will help us filter the data corresponding to a task from the Workflow Business Data Document Library. The Title field is the concatenation of the Related Content field in the main data connection and the string “.xml“.

Figure 11. Selecting the Title field and LeaveDaysUsedTillToday field

h. Click Next.

Figure 12. Data Connection Wizard

i. Click Finish.

Figure 13. Finishing the Data Connection Wizard

j. Close the Data Connections dialog box that now has the data connection to the Workflow Business Data Document Library.

Figure 14. Data Connections dialog box with the new data connection

4. Click in the second column of the new row that we inserted in step 3. On the Home tab in the ribbon, click Calculated Value (fx) button in the Controls pane.

Figure 15. Choosing Calculated Value in InfoPath

The Insert Calculated Value dialog box appears.

5. Click the fx button next to the XPath text box.

Figure 16. Insert Calculated Value dialog box

The Insert Formula dialog box appears as shown in the following figure.

6. Click Insert Field or Group.

Figure 17. Insert Field or Group button

The Select a Field or Group dialog box appears, as shown in the following figure.

7. Click Show advanced view.

Figure 18. Show advanced view link

Now, we have the option to select the data connection also. 

Figure 19. Select a Field or Group dialog box

8. Select the secondary data connection to the Workflow Business Document Library from the drop-down list.

Figure 20. Choosing a secondary data connection

9. Expand the dataFields tree structure until you see LeaveDaysUsedTillToday. SelectLeaveDaysUsedTillToday. Since we want to get only the business property for the corresponding task, we need to filter the data received from the data connection. Click Filter Data.

Figure 21. Filter Data button

10. The Filter Data dialog box appears. Click Add.

Figure 22. Add button in the Filter Data dialog box

The Specify Filter Conditions dialog box appears.

Figure 23. Specify Filter Conditions dialog box

11. Specify the filter conditions as follows:

a. In the first drop-down list, choose Select a field or group.

Figure 24. Choosing Select a field or group

b. Choose Workflow Business Data Document Library as the data source.

c. Expand the dataFields tree structure until you see Title. Select Title, and then click OK.

Figure 25. Title in the Select a Field or Group dialog box

d. In the second drop-down list in the Specify Filter Conditions dialog box, select is equal to.

e. In the third drop-down list in the Specify Filter Conditions dialog box, select Use a formula.

Figure 26. Selecting Use a formula in the list

f. The Insert Formula dialog box opens. Click Insert Function.

Figure 27. Insert Function button

The Insert Function dialog box opens.

Figure 28. Insert Function dialog box

g. Select Text in the Categories list, and then select concat in the Functions list. Click OK.

Figure 29. Choosing category and function

The formula corresponding to the selection appears in the Insert Formula dialog box.

Figure 30. Concat Formula prototype (skeleton) in the Insert Formula dialog box

h. Double-click the first argument in the concat function. The Select a Field or Group dialog box opens. Under the Main data connection, expand the dataFields tree structure till you see Related Content. Select the subfield :Description under Related Content. Click OK.

Figure 31. :Description subfield under Related Content

i. Write the string “.xml” as the second argument in the concat function. Delete the comma following the second argument and the third argument.

The updated formula is as shown in the following figure. Click OK.

Figure 32. Updated concat formula (with provided arguments) in Insert Formula dialog box

j. Click OK in the dialog boxes in the order: Specify Filter Conditions, Filter Data, Select a Field or Group.

The final overall formula appears in the Insert Formula dialog box. (This dialog box was opened in step 5 and is still open)

Figure 33. Final formula in the Insert Formula dialog box

12. Click OK in the Insert Formula dialog box (shown above) to return to the Insert Calculated Valuedialog box where the XPath corresponding to our selections has been updated.

Figure 34. Updated XPath in the Insert Calculated Value dialog box

Click OK.

13. Click the File tab on the ribbon. Click Quick Publish.

Figure 35. Publish your form

14. The Save As dialog box opens.

Figure 36. Saving the form template

15. Click Save. The Microsoft InfoPath dialog box stating the successful publishing of the form template appears. Click OK.

Figure 37. Form template published successfully

16. Open the task site and look up any of the tasks. The task appears as shown in the following figure. The SAP business property LeavesUsedTillToday has the value 10 in this task.

Figure 38. Task on the task site with LeavesUsedTillToday business property

Adding and deleting controls on a form

Suppose we want to add a control—for example, ID—from the main data connection to the workflow task form, and delete the control Consolidated Comments from the form.

1. Insert a new row for the ID field.

Figure 39. Inserting a new row for the ID field

2.  Drag the ID field from the Fields task pane onto the canvas. The label for the control appears automatically in the left column when you drag the field into the right column of the table. However, this is true only if you highlight both columns when you release the mouse.

Figure 40. ID field in right column

3. Delete the row containing the control for Consolidated Comments.

Figure 41. Consolidated Comments row deleted

3. Click the File tab on the ribbon. Click Quick Publish. The Microsoft InfoPath dialog box stating the successful publishing of the form template appears.

4. Click OK.

5. Open the task site and look up any of the tasks. The task appears as shown in the following figure. The task has the ID field with value 1 and no Consolidated Comments control.

Figure 42. Task on the task site with ID control and without Consolidated Comments control

Adding heading images to the form and applying a theme

1. Place your cursor in the title area of the page layout. Add a title—for example, MyTask—in the required format and font.

Figure 43. Title area of the page layout

2. Add the heading image to the form by inserting a picture from the Insert tab on the ribbon.

3. On the Page Design tab, apply the Professional – Standard theme. The easiest way to select the theme is to expand the Themes gallery by clicking the arrow at the lower-right corner. Professional – Standard is the first theme in the Professional section.

Figure 44. Page Design tab

The title, heading image, and page design should now resemble the following figure.

Figure 45. New title, heading image, and page design

4. Click the File tab on the ribbon. Click Quick Publish. The Microsoft InfoPath dialog box stating the successful publishing of the form template appears.

5. Click OK.

6. Open the task site and look up any of the tasks. The task appears as shown in the following figure. The task has the desired heading image and theme.

Figure 46. Task on the task site with desired heading image and theme

Your favourite Apps showcased here by SharePoint Samurai Studios will be available for use/download in App Stores Soon!!

Seller Dashboard account approved

		Congratulations! Your account in the Microsoft Seller Dashboard is approved. You can sign in to the Seller Dashboard, and do the following: Add apps and submit them for approval. Add or update payout information. If you want to list your apps for purchase, you need to provide payout information. If you want to list your apps as free, then payout information is not required. Check the approval status of your submitted apps. For more information, see Add Apps in the Microsoft Seller Dashboard. Sincerely, Seller Dashboard Team Note: This message was sent from an unmonitored email address. Please do not reply to this message. If you have questions or need help, please see Seller Dashboard Help.
		Microsoft Corporation | One Microsoft Way Redmond, WA 98052-6399 Microsoft respects your privacy. To learn more, please read our Privacy Statement. Legal Information

SharePoint Development roles urgently needs to be filled at MS Gold Partner – Contact me now for more information (Sorry, No recruiters, i am filling private positions)

Senior SharePoint Developers needed urgently for MS Gold Partner in Sandton/Bryanston :

3 – 5 years of development experience.

2 year experience in SharePoint.

3 years experience in C#.

A minimum of 3 years experience in Visual Studio .NET 2005 – 2008.

A minimum of 3 years experience in ASP.NET , HTML web development.

A minimum of 3 years experience with Javascript.

A minimum of 3 years experience with Windows XP, Windows 2003 and Windows Vista.

A minimum of 3 years experience in relational database design and implementation with SQL Server
Advantageous (nice-to-have):

• Windows SharePoint Server.
• Microsoft Office SharePoint Server.
• BizTalk
• Web Analytics
• Microsoft CRM
• K2

Creating Nintex Workflow Custom Actions

Nintex is a great product to create Workflows with within SharePoint. Much more flexible than SharePoint Designer, and far less complicated than using Visual Studio. There is an extensive list of Actions already for Nintex Workflow sometimes you need a Custom Action that is specific for your business such as bring back data from your bespoke application, or UNIX text file. This blog will explain the different parts of creating a custom action to you.

Above picture showing you collection of Actions that comes with Nintex Workflow.

To build a custom action, unfortunately, there is a collection of files you are require to create, even though there is only one real section that performs the actual business logic. The rest of it is all supporting code. Below is a basic project setup of all the files you need. I will explain each section throughout this post. With a walkthrough at the end of how to create a ReadFromPropertyBag Custom Action.

References

Before we can even start we require the following References.

• System.Workflow.Activities.dll (Not shown in above picture. Forgot to add before took picture.)
• Microsoft.SharePoint.dll
• Microsoft.SharePoint.WorkflowActions.dll
• System.Workflow.ComponentModel.dll
• Nintex.Workflow.dll – Can be found at C:\Program Files\Nintex\Nintex Workflow 2010\Binaries.
• Nintex.Workflow.ServerControls.dll – Can be found at C:\Program Files\Nintex\Nintex Workflow 2010\Binaries. (Not shown in above picture. Forgot to add before took picture.)

Features

A WebApplication feature that when activated it will add the Custom Action to the Web Application and authorize it to be used within the web application.

CustomActions –ActionName – NWAFile

An element file, which holds an XML file which is all the required details for a NintexWorkflowActivity. It is this file that is read in by the Feature receiver to be able to add the custom action to the web application.

CustomActions – ActionName – ActionNameActivity

A class that is inherited by Nintex.Workflow.Activities.ProgressTrackingActivity. This file contains all the Dependency properties to the activity. The Dependency Properties are object properties that can be bound to other elements of a workflow, such as workflow variables or dependency properties of other activities. They are used to store the data that the activity will require or to output data from the activity. This is also the file that contains the execution of the actual business logic.

CustomActions – ActionName – ActionNameAdapter

A class that is inherited by Nintex.Workflow.Activities.Adapters.GenericRenderingAction. You will need to implement the abstract class of GenericRenderingAction. These implementations

• GetDefaultConfig() – define the parameters that the user can configure for this action and sets the default label for the action.
• ValidateConfig() – Adds logic to validate the configuration here, and will display any error messages to the user if there is an issue.
• AddActivityToWorkflow() – Creates an instance of the Activity and set its properties based on config. Then it adds it to the parent activity.
• GetConfig() – Reads the property from the context.Activity and update the values in the NWActionConfig.
• BuildSummary() – Constructs an Action Summary class to display details about this action.

I find the Adapter is very similar for every Action. Once you have the basic of one, just by adding an extra parameter or removing one you can quickly put an adapter together for any Custom Action.

Layouts – NintexWorkflow – CustomActions – ActionName – Images

I have two icon .png files in here. One is sized at 49×49 pixels and the other at 30×30 pixels. These files are referenced in the NWAFile, and used to display the custom action to the user in the toolbox area (30×30), or in the actual workflow itself (49×49).

You could add a third one here for Warning Icon. This is where the custom action isn’t configured. This would be a 49×49 pixel too.

Layouts – NintexWorkflow – CustomActions – ActionName – ActionNameDialog

An application page inherited from Nintex.Workflow.ServerControls.NintexLayoutBase. The dialog is what appears to the user when they have to configure the custom action through the browser. Here there is no code behind. You mainly display the controls in the aspx and set up two javascript functions to read in and read out the configuration on load and save.

Walkthrough creating ReadFromPropertyBag Custom Action.

Now that you understand the basic roles of all the files required to make one custom action I will walk through creating a custom action that will read from the current SPWeb property bag. The user will pass in the “Property name” to obtain the value.

If you create a Solution with the similar layout my solution layout above, replacing “ActionName” with ReadFromPropertyBag. Your solution and file layouts should look similar to below.

ReadFromPropertyBagActivity.cs

Starting with the ReadFromPropertyBagActivity file. This inherits Nintex.Workflow.Activities.ProgressTrackingActivity. We will first add all the public static DependencyProperties. The default ones are __ListItem, __Context and __ListId. Then we will add 2 of our own, One to hold the the Property Name and the ResultOuput. You can delete the designer.cs file.

Each DependencyProperty will have its own public property.

using System; using System.Workflow.ComponentModel; using Microsoft.SharePoint.Workflow; using Microsoft.SharePoint.WorkflowActions; using Nintex.Workflow; using Microsoft.SharePoint; namespace CFSP.CustomActions.ReadFromPropertyBag {     public class ReadFromPropertyBagActivity : Nintex.Workflow.Activities.ProgressTrackingActivity     {         public static DependencyProperty __ListItemProperty = DependencyProperty.Register("__ListItem", typeof (SPItemKey), typeof (ReadFromPropertyBagActivity));         public static DependencyProperty __ContextProperty = DependencyProperty.Register("__Context", typeof (WorkflowContext), typeof (ReadFromPropertyBagActivity));           public static DependencyProperty __ListIdProperty = DependencyProperty.Register("__ListId", typeof (string),typeof (ReadFromPropertyBagActivity));         public static DependencyProperty PropertyProperty = DependencyProperty.Register("Property", typeof (string), typeof (ReadFromPropertyBagActivity));         public static DependencyProperty ResultOutputProperty = DependencyProperty.Register("ResultOutput", typeof (string), typeof (ReadFromPropertyBagActivity));           public WorkflowContext __Context         {             get { return (WorkflowContext) base.GetValue(__ContextProperty); }             set { base.SetValue(__ContextProperty, value); }         }           public SPItemKey __ListItem         {             get { return (SPItemKey) base.GetValue(__ListItemProperty); }             set { base.SetValue(__ListItemProperty, value); }         }           public string __ListId         {             get { return (string) base.GetValue(__ListIdProperty); }             set { base.SetValue(__ListIdProperty, value);}         }           public string Property         {             get { return (string) base.GetValue(PropertyProperty); }             set { base.SetValue(PropertyProperty, value);}         }           public string ResultOutput         {             get { return (string) base.GetValue(ResultOutputProperty); }             set {base.SetValue(ResultOutputProperty, value);}         }           public ReadFromPropertyBagActivity()         {         }          protected override ActivityExecutionStatus Execute(ActivityExecutionContext executionContext)         {         }         protected override ActivityExecutionStatus HandleFault(ActivityExecutionContext executionContext, Exception exception)         {         }     } }

Now we will need to override the Execute() method. This is the main business logic of your Custom Action.

protected override ActivityExecutionStatus Execute(ActivityExecutionContext executionContext)      {          //Standard Nintex code to obtain context.          ActivityActivationReference.IsAllowed(this, __Context.Web);          NWWorkflowContext ctx = NWWorkflowContext.GetContext(             this.__Context,             new Guid(this.__ListId),             this.__ListItem.Id,             this.WorkflowInstanceId,             this);            base.LogProgressStart(ctx);          //Get the property value.          string resolvedProperty = ctx.AddContextDataToString(this.Property);            var result = "";            //Using the context get the property if it exists.          if (ctx.Web.AllProperties.ContainsKey(resolvedProperty))          {              result = ctx.Web.AllProperties[resolvedProperty].ToString();          }          //store the result.          this.ResultOutput = result;            //End Execution.          base.LogProgressEnd(ctx, executionContext);          return ActivityExecutionStatus.Closed;     }

The last thing we need to do in this class is to handle if there is a fault during execution. Overwrite the HandleFault code with the following. You can make the error say whatever you like. I’m just referencing the item that called the workflow.

protected override ActivityExecutionStatus HandleFault(ActivityExecutionContext executionContext, Exception exception)         {             Nintex.Workflow.Diagnostics.ActivityErrorHandler.HandleFault(executionContext, exception,                 this.WorkflowInstanceId, "Error Reading from Property Bag", __ListItem.Id, __ListId, __Context);             return base.HandleFault(executionContext, exception);         }

ReadFromPropertyBagAdapter.cs

Moving onto the Adapter file now. This class inherits the Nintex.Workflow.Activies.Adapters.GenericRenderingAction and needs to implement 5 overrides. I have also included two private constants strings. These are the property names we declared in the Activity class. Ensure these names match, or you will encounter errors later which takes a while to debug.

using System; using System.Collections.Generic; using System.Workflow.ComponentModel; using Microsoft.SharePoint; using Nintex.Workflow; using Nintex.Workflow.Activities.Adapters;   namespace CFSP.CustomActions.ReadFromPropertyBag {     public class ReadFromPropertyBagAdapter : GenericRenderingAction     {        //Values should match the property names in the ReadFromPropertyBagActivity class.         private const string PropertyProperty = "Property";         private const string ResultOutputProperty = "ResultOutput";          public override NWActionConfig GetDefaultConfig(GetDefaultConfigContext context)         {             throw new NotImplementedException();         }           public override bool ValidateConfig(ActivityContext context)         {             throw new NotImplementedException();         }         public override CompositeActivity AddActivityToWorkflow(PublishContext context)         {             throw new NotImplementedException();         }           public override NWActionConfig GetConfig(RetrieveConfigContext context)         {             throw new NotImplementedException();         }           public override ActionSummary BuildSummary(ActivityContext context)         {             throw new NotImplementedException();         }    } }

I will explain each override before showing you the code.

GetDefaultConfig sections allows you to set up the parameters for user input and outputs. If you wish the user to freely type a value use a PrimitiveValue. If you would like the user to use a predefined value that would be a variable somewhere in the workflow then use NWWorkflowVariable value. Typically the output would always be written back to a Workflow Variable so this will be a Variable type of NWWorkflowVariable. Add an ActivityParameter for each property.

public override NWActionConfig GetDefaultConfig(GetDefaultConfigContext context)        {             NWActionConfig config = new NWActionConfig(this);             //define the number of parameters one for each custom parameter.             config.Parameters = new ActivityParameter[2];             //define the parameters that the user can configure for this action.             config.Parameters[0] = new ActivityParameter();             config.Parameters[0].Name = PropertyProperty;             config.Parameters[0].PrimitiveValue = new PrimitiveValue();             config.Parameters[0].PrimitiveValue.Value = string.Empty;             config.Parameters[0].PrimitiveValue.ValueType = SPFieldType.Text.ToString();               config.Parameters[1] = new ActivityParameter();             config.Parameters[1].Name = ResultOutputProperty;             config.Parameters[1].Variable = new NWWorkflowVariable();               //set the default label for the action.             config.TLabel = ActivityReferenceCollection.FindByAdapter(this).Name;             return config;        }

ValidateConfig section allows you to validate the values entered. Here I’m just ensuring the value are not blank. You would add a validation for each input property.

public override bool ValidateConfig(ActivityContext context) {             //Add logic to validate the configuration here.             bool isValid = true;             Dictionary<string, ActivityParameterHelper> parameters = context.Configuration.GetParameterHelpers();             if (!parameters[PropertyProperty].Validate(typeof(string), context))             {                 isValid &= false;                 validationSummary.AddError("Property Bag", ValidationSummaryErrorType.CannotBeBlank);             }             return isValid; }

Validation is shown in image below.

AddActivityToWorkflow creates an instance of the Activity and set its properties based on config. You also bind the default properties. Assign each parameter you have here. Lastly attach the Activity Flags. Then add it all to the parent activity.

<strong>  </strong>public override CompositeActivity AddActivityToWorkflow(PublishContext context)         {             Dictionary<string, ActivityParameterHelper> parameters = context.Config.GetParameterHelpers();             ReadFromPropertyBagActivity activity = new ReadFromPropertyBagActivity();               parameters[PropertyProperty].AssignTo(activity, ReadFromPropertyBagActivity.PropertyProperty, context);             parameters[ResultOutputProperty].AssignTo(activity, ReadFromPropertyBagActivity.ResultOutputProperty, context);             activity.SetBinding(ReadFromPropertyBagActivity.__ContextProperty, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__context));             activity.SetBinding(ReadFromPropertyBagActivity.__ListItemProperty, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__item));               activity.SetBinding(ReadFromPropertyBagActivity.__ListIdProperty, new ActivityBind(context.ParentWorkflow.Name, StandardWorkflowDataItems.__list));               ActivityFlags f = new ActivityFlags();             f.AddLabelsFromConfig(context);             f.AssignTo(activity);               context.ParentActivity.Activities.Add(activity);             return null;         }

GetConfig reads the properties from the context.Activity and updates the values in the NWActionConfig. Add a new parameter for each property. You can see when we RetrieveValue from our activity, we are grabbing the corresponding DependencyProperty from our activity.

public override NWActionConfig GetConfig(RetrieveConfigContext context)         {             //Read the properties from the context.ACtivity and update the values in the NWActionConfig               NWActionConfig config = this.GetDefaultConfig(context);             Dictionary<string, ActivityParameterHelper> parameters = config.GetParameterHelpers();             parameters[PropertyProperty].RetrieveValue(context.Activity, ReadFromPropertyBagActivity.PropertyProperty, context);             parameters[ResultOutputProperty].RetrieveValue(context.Activity, ReadFromPropertyBagActivity.ResultOutputProperty, context);               return config;           }

BuildSummary is the last implemented override method. The code here writes out the summary displayed to the user after that have configured the action and hovered the mouse over the custom action.

public override ActionSummary BuildSummary(ActivityContext context)         {            // Construct an ActionSummary class to display details about this action.               Dictionary<string, ActivityParameterHelper> parameters = context.Configuration.GetParameterHelpers();             return new ActionSummary("Retrieve the following Property bag: {0}", parameters[PropertyProperty].Value);           }

BuildSummary is displayed below on mouse hover once item has been configured.

ReadFromPropertyBagDialog.aspx

The code behind for this aspx file inherits from Nintex.Workflow.ServerControls.NintexLayoutsBase. Apart from changing the inheriting type, there is no need to do anything else in the .cs file. In the aspx file we would have the basic structure. This structure contains the link up to your page behind, register all the Nintex controls required, the two main JavaScript functions to read and save the configuration, and lastly the display section of your page.

<%@ Page Language="C#" DynamicMasterPageFile="~masterurl/default.master" AutoEventWireup="true" CodeBehind="ReadFromPropertyBagDialog.aspx.cs" EnableEventValidation="false"       Inherits="CFSP.CustomActions.ReadFromPropertyBag.ReadFromPropertyBagDialog, $SharePoint.Project.AssemblyFullName$" %> <%@ Register TagPrefix="Nintex" Namespace="Nintex.Workflow.ServerControls" Assembly="Nintex.Workflow.ServerControls, Version=1.0.0.0, Culture=neutral, PublicKeyToken=913f6bae0ca5ae12" %>   <%@ Register TagPrefix="Nintex" TagName="ConfigurationPropertySection" src="~/_layouts/NintexWorkflow/ConfigurationPropertySection.ascx" %>   <%@ Register TagPrefix="Nintex" TagName="ConfigurationProperty" src="~/_layouts/NintexWorkflow/ConfigurationProperty.ascx" %>   <%@ Register TagPrefix="Nintex" TagName="DialogLoad" Src="~/_layouts/NintexWorkflow/DialogLoad.ascx" %>   <%@ Register TagPrefix="Nintex" TagName="DialogBody" Src="~/_layouts/NintexWorkflow/DialogBody.ascx" %>   <%@ Register TagPrefix="Nintex" TagName="SingleLineInput" Src="~/_layouts/NintexWorkflow/SingleLineInput.ascx" %>   <%@ Register TagPrefix="Nintex" TagName="PlainTextWebControl" Src="~/_layouts/NintexWorkflow/PlainTextWebControl.ascx" %>   <asp:Content ID="ContentHead" ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server">       <Nintex:DialogLoad runat="server" />     <script type="text/javascript" language="javascript">         function TPARetrieveConfig() {        //To Do         }           function TPAWriteConfig() {         //To Do         }           onLoadFunctions[onLoadFunctions.length] = function () {             dialogSectionsArray["<%= MainControls1.ClientID %>"] = true;         };     </script> </asp:Content>   <asp:Content ID="ContentBody" ContentPlaceHolderID="PlaceHolderMain" runat="Server">   <Nintex:ConfigurationPropertySection runat="server" Id="MainControls1">              <TemplateRowsArea>                    <!--ToDo-->               </TemplateRowsArea>  </Nintex:ConfigurationPropertySection>     <Nintex:DialogBody runat="server" id="DialogBody">   </Nintex:DialogBody> </asp:Content>

First section we will fill in will be the Nintex:ConfigurationPropertySection within the ContentPlaceHolderID PlaceHolderMain. In here we need to create a Nintex:ConfigurationProperty for each configuration property. In our case here that will be the Property Bag Name and the Result. You can see from below for consistency I have given the ID of the controls the same name as the Dependency Properties. Also note that the output because I’m want the user to assign the results to a workflow property, I’m using the Nintex:VariableSelector control.

<Nintex:ConfigurationProperty runat="server" FieldTitle="Property Bag Property" RequiredField="True">        <TemplateControlArea>             <Nintex:SingleLineInput clearFieldOnInsert="true" filter="number" runat="server" id="propertyProperty"></Nintex:SingleLineInput>       </TemplateControlArea>     </Nintex:ConfigurationProperty>     <Nintex:ConfigurationProperty runat="server" FieldTitle="Result Output" RequiredField="False">       <TemplateControlArea>         <Nintex:VariableSelector id="resultOutput" runat="server" IncludeTextVars="True"></Nintex:VariableSelector>       </TemplateControlArea>       </Nintex:ConfigurationProperty>

Next we are going to look at the two JavaScript files. When the dialog page is rendered and saved it passed an XML file, known as the configXml. We need to read out and read into the XML file using XPath. Please note when you come to deploying, if you find that your dialog control loads, however the ribbon bar is disabled at the top of the dialog, it is most likely that you have an error in the JavaScript. This took me a while to diagnose, but now I know what causes the issue, it allowed me to fix it straight away.

From the TPARetrieveConfig code the [@Name=’ ‘] will always be the public property name you gave it in the ReadFromPropertyBagActivity.cs file. As you can see from the code below there is a different way to obtain the value depending if the configuration property is a PrimitiveValue or a WorkflowVariable. This you defined in the GetDefaultConfig() method within the ReadFromPropertyBagAdapter.cs file. Lastly if you are still having problems getting the value, ensure your XPath is correct by debugging the Javascript and viewing the configXML variable.

function TPARetrieveConfig() {            setRTEValue('<%=propertyProperty.ClientID%>', configXml.selectSingleNode("/NWActionConfig/Parameters/Parameter[@Name='Property']/PrimitiveValue/@Value").text);              document.getElementById('<%=resultOutput.ClientID%>').value = configXml.selectSingleNode("/NWActionConfig/Parameters/Parameter[@Name='ResultOutput']/Variable/@Name").text;          }

From the TPAWriteConfig code it is basically doing the opposite of TPARetrieveConfig, just it checks the dropdown control (resultOutput) that a value has been selected before saving.

function TPAWriteConfig() {            configXml.selectSingleNode("/NWActionConfig/Parameters/Parameter[@Name='Property']/PrimitiveValue/@Value").text = getRTEValue('<%=propertyProperty.ClientID%>');              var resultOuputCtrl = document.getElementById('<%=resultOutput.ClientID%>');              if (resultOuputCtrl.value.length > 0) {                configXml.selectSingleNode("/NWActionConfig/Parameters/Parameter[@Name='ResultOutput']/Variable/@Name").text = resultOuputCtrl.value;            }              return true;        }

ReadFromPropertyBagAction.nwa

The NWA file as stated previously is just an XML file. This file is used by the Feature Receiver to register the custom action within SharePoint WebApplication.

First thing we need to do is from the properties window (press F4) we need to change the build action from None to Content, change the deployment type to ElementFile and remove the Path “\NWAFile”.

From within the XML file, remove all text and then place the following in.

<NintexWorkflowActivity>   <Name>Retrieve from Property Bag</Name>   <Category>CannonFodder Category</Category>   <Description>A custom action to retrieve a property from the SharePoint Web Property Bag.</Description>   <ActivityType>CFSP.CustomActions.ReadFromPropertyBag.ReadFromPropertyBagActivity</ActivityType>   <ActivityAssembly>$SharePoint.Project.AssemblyFullName$</ActivityAssembly>   <AdapterType>CFSP.CustomActions.ReadFromPropertyBag.ReadFromPropertyBagAdapter</AdapterType>   <AdapterAssembly>$SharePoint.Project.AssemblyFullName$</AdapterAssembly>   <HandlerUrl>ActivityServer.ashx</HandlerUrl>   <Icon>/_layouts/NintexWorkflow/CustomActions/ReadFromPropertyBag/Images/ReadFromPropertyBagIcon49x49.png</Icon>   <ToolboxIcon>/_layouts/NintexWorkflow/CustomActions/ReadFromPropertyBag/Images/ReadFromPropertyBagIconSmall30x30.png</ToolboxIcon>   <ConfigurationDialogUrl>CustomActions/ReadFromPropertyBag/ReadFromPropertyBagDialog.aspx</ConfigurationDialogUrl>   <ShowInCommonActions>yes</ShowInCommonActions>   <DocumentLibrariesOnly>no</DocumentLibrariesOnly> </NintexWorkflowActivity>

Let me explain each line to you.

• Name – The display name of the custom action
• Category – The category in the toolbox area that the custom action will be displayed under.
• Description – A description of the category.
• ActivityType – The Namespace of the Activity.cs file.
• ActivityAssembly – The Full assembly name. (I’m using a token, which I’ll show how to set up afterwards)
• AdapterType – The Namespace of the Adapter.cs file.
• AdapterAssembly – The full assembly name. (I’m using a token, which I’ll show how to set up afterwards)
• HandlerUrl – The Nintex handler, this will always be ActivityServer.ashx
• Icon – The URL to the larger Icon.
• ToolboxIcon – The URL to the smaller icon.
• WarningIcon – The URL to the Warning Icon <-Not used in the above XML.
• ConfigurationDialogUrl – The URL to the Action Dialog file. Note that we don’t put /_layouts/NintexWorkflow at the front.
• ShowInCommonActions – If this custom action shows up in CommonActions on the toolbox.
• DocumentLibrariesOnly – If this custom action should only be used in DocumentLibraries or not.

Getting the Token $SharePoint.Project.AssemblyFullName$ to replace on a build.

At this point, save and close your solution. Now open up your .csproj file in Notepad or Notepad++. At the bottom of your first <PropertyGroup> section add the following XML. Save the file and re-open your solution in Visual Studio.

<TokenReplacementFileExtensions>nwa</TokenReplacementFileExtensions>

When you build your solution, Visual Studio will replace your token with the actual Full Assembly Name. More information about TokenReplacementFileExtensions.

WebApplication – Custom Action EventReceiver.cs

The Feature Event receiver is the final piece to our custom action. This will deploy or remove our custom action and make it available to the Web Application by modifying the Web.Config and registering the Action with Nintex within the farm. To add the custom action we use the nwa file. To remove it we need to know the namespace of the adapter, and assembly name. As you build more custom actions you can reuse this feature and just de-activate and re-activate each time you deploy a new custom action.

using System; using System.Collections.ObjectModel; using System.IO; using System.Runtime.InteropServices; using System.Xml; using Microsoft.SharePoint; using Microsoft.SharePoint.Administration; using Nintex.Workflow; using Nintex.Workflow.Administration; using Nintex.Workflow.Common; using System.Reflection; namespace CFSP.CustomActions.Features.WebApplication___Custom_Actions {     [Guid("07607091-449b-422b-94e4-84e6d863eb9e")]     public class WebApplication___Custom_ActionsEventReceiver : SPFeatureReceiver     {         public override void FeatureActivated(SPFeatureReceiverProperties properties)         {             SPWebApplication parent = (SPWebApplication) properties.Feature.Parent;             AddCustomAction(parent, properties, "ReadFromPropertyBagAction.nwa");            //Add additional Custom Actions nwa files here.         }         public override void FeatureDeactivating(SPFeatureReceiverProperties properties)         {             SPWebApplication parent = (SPWebApplication) properties.Feature.Parent;             RemoveCustomAction(parent, properties,                 "CFSP.CustomActions.ReadFromPropertyBag.ReadFromPropertyBagAdapter",                 Assembly.GetExecutingAssembly().FullName);            //Remove additional Custom Actions here.         }           protected void AddCustomAction(SPWebApplication parent, SPFeatureReceiverProperties properties,             string pathToNWAFile)         {             // First step is register the action to the Nintex Workflow database             XmlDocument nwaXml = GetNWADefinition(properties, pathToNWAFile);               ActivityReference newActivityReference = ActivityReference.ReadFromNWA(nwaXml);               ActivityReference action = ActivityReferenceCollection.FindByAdapter(newActivityReference.AdapterType,                 newActivityReference.AdapterAssembly);               if (action != null)             {                 // update the details if the adapter already exists                 ActivityReferenceCollection.UpdateActivity(action.ActivityId, newActivityReference.Name,                     newActivityReference.Description, newActivityReference.Category,                     newActivityReference.ActivityAssembly, newActivityReference.ActivityType,                     newActivityReference.AdapterAssembly, newActivityReference.AdapterType,                     newActivityReference.HandlerUrl, newActivityReference.ConfigPage,                     newActivityReference.RenderBehaviour, newActivityReference.Icon, newActivityReference.ToolboxIcon,                     newActivityReference.WarningIcon, newActivityReference.QuickAccess,                     newActivityReference.ListTypeFilter);             }             else             {                 ActivityReferenceCollection.AddActivity(newActivityReference.Name, newActivityReference.Description,                     newActivityReference.Category, newActivityReference.ActivityAssembly,                     newActivityReference.ActivityType, newActivityReference.AdapterAssembly,                     newActivityReference.AdapterType, newActivityReference.HandlerUrl, newActivityReference.ConfigPage,                     newActivityReference.RenderBehaviour, newActivityReference.Icon, newActivityReference.ToolboxIcon,                     newActivityReference.WarningIcon, newActivityReference.QuickAccess,                     newActivityReference.ListTypeFilter);                 action = ActivityReferenceCollection.FindByAdapter(newActivityReference.AdapterType,                     newActivityReference.AdapterAssembly);             }               // Second step is to modify the web.config file to allow use of the activity in declarative workflows             string activityTypeName = string.Empty;             string activityNamespace = string.Empty;               Utility.ExtractNamespaceAndClassName(action.ActivityType, out activityTypeName, out activityNamespace);             AuthorisedTypes.InstallAuthorizedWorkflowTypes(parent, action.ActivityAssembly, activityNamespace,                 activityTypeName);             // Third step is to activate the action for the farm             ActivityActivationReference reference = new ActivityActivationReference(action.ActivityId, Guid.Empty,                 Guid.Empty);               reference.AddOrUpdateActivationReference();         }         protected void RemoveCustomAction(SPWebApplication parent, SPFeatureReceiverProperties properties,             string adapterType, string adapterAssembly)         {             ActivityReference action = ActivityReferenceCollection.FindByAdapter(adapterType, adapterAssembly);             if (action != null)             {                 // Remove the action definition from the workflow configuration database if the Feature is not activated elsewhere                 if (!IsFeatureActivatedInAnyWebApp(parent, properties.Definition.Id))                     ActivityReferenceCollection.RemoveAction(action.ActivityId);                 string activityTypeName = string.Empty;                 string activityNamespace = string.Empty;                 Utility.ExtractNamespaceAndClassName(action.ActivityType, out activityTypeName, out activityNamespace);                   // Remove the web.config entry                 Collection<SPWebConfigModification> modifications = parent.WebConfigModifications;                   foreach (SPWebConfigModification modification in modifications)                 {                     if (modification.Owner == AuthorisedTypes.OWNER_TOKEN)                         // OWNER_TOKEN is the owner for any web config modification added by Nintex Workflow                     {                         if (IsAuthorizedTypeMatch(modification.Value, action.ActivityAssembly, activityTypeName,                             activityNamespace))                         {                             modifications.Remove(modification);                             parent.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();                            break;                         }                     }                 }             }         }         private bool IsAuthorizedTypeMatch(string modification, string activityAssembly, string activityType,             string activityNamespace)         {             XmlDocument doc = new XmlDocument();             doc.LoadXml(modification);               if (doc.FirstChild.Name == "authorizedType")             {                 return (doc.SelectSingleNode("//@TypeName").Value == activityType                         && doc.SelectSingleNode("//@Namespace").Value == activityNamespace                         && doc.SelectSingleNode("//@Assembly").Value == activityAssembly);             }             return false;         }           private bool IsFeatureActivatedInAnyWebApp(SPWebApplication thisWebApplication, Guid thisFeatureId)         {             SPWebService webService = SPWebService.ContentService;             if (webService == null)                 throw new ApplicationException("Cannot access ContentService");             SPWebApplicationCollection webApps = webService.WebApplications;             foreach (SPWebApplication webApp in webApps)             {                 if (webApp != thisWebApplication)                     if (webApp.Features[thisFeatureId] != null)                         return true;             }               return false;         }           private XmlDocument GetNWADefinition(SPFeatureReceiverProperties properties, string pathToNWAFile)         {             using (Stream stream = properties.Definition.GetFile(pathToNWAFile))             {                 XmlDocument nwaXml = new XmlDocument();                 nwaXml.Load(stream);                 return nwaXml;             }         }    } }

Deploying and checking everything has worked.

If you have done everything correctly, at the point go ahead and deploy your solution. Ensure your feature has been activated for a given web application. Then open Central Admin. Under the Nintex Workflow Management section select Manage allowed actions.

In Manage Allowed action you should see your Action, and that it is ticked. Meaning it is allowed to be used.

Let us go to our site now, and create a new Nintex Workflow for our custom list. My list has a Single line of text called Title and another one called PropertyValue. In the toolbar panel of my Nintex Workflow, I can now see my CannonFodder Category, and my custom action.

Drag this onto your page. If you find it doesn’t stick to your workflow page, go back and check your nwa file that all your Types and Assemblies match up correctly. Once it is on your page, configure this custom action. Your dialog will be presented to you.

Assign the Property Bag Property to the Item Property Title.

Create a new Workflow Variable and name this PBResult. Then assign Result Output to PBResult. Click Save on the dialog.

Under Libraries and List find the action Set field value and drag this onto the form underneath our custom action. Then configure it so that it sets our column PropertyValue to Workflow Data called PBResult that we created in the last step. Click Save on the dialog.

Lastly before we test this out, on the ribbon bar of the workflow page, under the Nintex Workflow 2010 tab, click Workflow Settings. Configure it so that it Starts when items are created.

Save and Publish the workflow.

Testing

I already have a value in my property bag called cann0nf0dderpb. So I’m going to create a new item in my list, and set the title to cann0nf0dderpb and save the form.

After a moment or two the workflow has kicked in. Once I refresh my list I can see that in PropertyValue, the value of my PropertyBag item is displayed. I purposely made the property bag value say ‘Nintex Workflow Worked’.

Debugging SharePoint 2013 workflows using Visual Studio 2013

   Learn about the new tools for remotely debugging workflows in Visual Studio 2012

 

In Office Developer Tools for Visual Studio 2012, we enabled remote event debugging using Windows Azure Service Bus.

Now, in Visual Studio 2013, we have implemented a similar approach for remotely debugging workflows in apps for SharePoint.

The new and re-worded debugging options are available on the SharePoint tab under the Properties page of your app for SharePoint project, as shown in Figure 1.

Figure 1. Configure remote event and workflow debugging

To debug workflows on Office 365, select the “Enable Workflow debugging” and “Enable debugging via Windows Azure Service Bus” check boxes and enter the Service Bus endpoint connection string. If you try to debug without providing a connection string, you will be prompted to supply one.

Figure 2. Prompt for a connection string

As mentioned in the previous blog post, you’ll need to follow these steps to use the Windows Azure Service Bus for debugging remote events:

1. Register for a Windows Azure account and then create a Service Bus namespace.
2. See Managing Service Bus Service Namespaces for more information about managing namespaces.
3. To get the Service Bus connection string, select your service namespace, choose Access Key, and then copy the Connection String.

After you have enabled remote event debugging and configured the Service Bus connection string, you can debug remote events.

FAQ

1. How can I turn on/off the notification from Visual Studio that tells me to provide a Service Bus connection string?      If you are debugging an Office 365 workflow in your project and have not configured Service Bus debugging, Visual Studio will prompt you to configure it (see Figure 2). You can change this behavior by clearing the Notify me if Windows Azure Service Bus debugging is not configured check box on the SharePoint project property page.
2. When do I need to enable the Service Bus debugging for workflows?      You must enable Service Bus debugging if you want to debug workflows on Office 365. If your project targets SharePoint installed on your local network, you do not need to enable Service Bus debugging. Instead, you need to open incoming connections to TCP port 12292. If you use Windows Firewall with Advanced Security, you can simply enable the rule “Workflow Manager Tools 1.0 for Visual Studio 2012 – Test Service Host”. If you try to debug against a SharePoint host on the local network without opening the port, Visual Studio will prompt you to enable the rule.
3. Do I have to enable Service Bus debugging for every project?      Even though you configure the settings in project properties, Service Bus debugging settings are saved for the current user of the workstation so that you can reuse the settings across different projects. However, this setting is not saved into source control (TFS), so if they are needed by a different user or on a different machine, they need to be entered again.
4. Will I be charged for Service Bus usage?      Yes. Remote event debugging uses the Relay Service component of the Service Bus. Refer to the Service Bus Pricing FAQ for more information.       If you are currently a Visual Studio Professional, Premium, or Ultimate with MSDN subscriber, you can check out the special offer on Windows Azure, which provides Service Bus Relay Hours of up to 1,500, 3,000, and 3,000 respectively.
5. Do I have to change debugging settings before I publish my app to the marketplace or to the Corporate Gallery?      No. The package created by the Publish command in Visual Studio has the .app extension and does not contain any debugging information. A separate package, having the .debugapp extension is the only one used during debugging.
6. Can I use Service Bus to debug workflows in SharePoint sandbox or farm solutions?      No. SharePoint solutions can only be debugged against SharePoint installed on the developer’s workstation.
7. Can I use Service Bus to debug SharePoint 2010 workflows?      No. You can only use it for debugging apps for SharePoint, and apps cannot contain SharePoint 2010 workflows.