Docstoc

Business_Scorecard_Manager_MSMQ_WP

Document Sample
Business_Scorecard_Manager_MSMQ_WP Powered By Docstoc
					Using MSMQ Triggers with Business
Scorecard Manager 2005




MSMQ Triggers     1
                This is a preliminary document and may be changed substantially prior to final commercial
                release of the software described herein. The information contained in this document represents
                the current view of Microsoft Corporation on the issues discussed as of the date of publication.
                Because Microsoft must respond to changing market conditions, it should not be interpreted to
                be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any
                information presented after the date of publication.

                This white paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES,
                EXPRESS OR IMPLIED, IN THIS DOCUMENT.

                Complying with all applicable copyright laws is the responsibility of the user. Without limiting the
                rights under copyright, no part of this document may be reproduced, stored in, or introduced into
                a retrieval system, or transmitted in any form or by any means (electronic, mechanical,
                photocopying, recording, or otherwise), or for any purpose, without the express written permission
                of Microsoft Corporation.

                Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual
                property rights covering subject matter in this document. Except as expressly provided in any
                written license agreement from Microsoft, the furnishing of this document does not give you any
                license to these patents, trademarks, copyrights, or other intellectual property.

                © 2005 Microsoft Corporation. All rights reserved.

                The example companies, organizations, products, domain names, e-mail addresses, logos,
                people, places, and events depicted herein are fictitious. No association with any real company,
                organization, product, domain name, e-mail address, logo, person, place, or event is intended or
                should be inferred.

                Microsoft, MSDN, Win32, Windows, Windows Server and the Office Logo are either registered
                trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.




MSMQ Triggers                                   2
Table of Contents
Introduction.....................................................................................................................................................4
Example of a Business Scorecard Manager MSMQ Message ......................................................................5
Using MSMQ Triggers To Process Messages from a Queue ........................................................................5
MSMQ Triggers ..............................................................................................................................................6
   Conditions ...................................................................................................................................................6
   Actions ........................................................................................................................................................6
   When do you use more than one trigger? ..................................................................................................6
   When do you use more than one rule? ......................................................................................................7
Sample Message Parser ................................................................................................................................7
Creating MSMQ Queues, Rules, and Triggers ........................................................................................... 12




MSMQ Triggers                                                             3
Introduction
      This white paper describes how to use Microsoft® Message Queuing Services (MSMQ) 3.0
      with Microsoft Office Business Scorecard Manager 2005. Readers should be familiar with
      MSMQ.
      MSMQ is ideal for use in a variety of systems as a means of transferring data because you
      can use it to send messages across machine boundaries to queues where a receiving
      application can retrieve them in a prioritized manner.
      MSMQ enables applications that run at different times to communicate across heterogeneous
      networks and across systems that might be temporarily offline. The applications send
      messages to queues and read messages from queues. Therefore, developers can use this tool
      to perform operations asynchronously, or in other words, to begin a process without waiting
      for an operation to complete.
      All Microsoft Office Business Scorecard Manager objects, which include key performance
      indicators (KPIs), scorecards, data sources, indicators, and annotations, trigger an event for
      every Create, Update, and Delete operation. If MSMQ is enabled on the Business Scorecard
      Manager server, these events generate messages that are stored in the MSMQ message queue
      that was specified in Microsoft Office Business Scorecard Builder when the scorecard was
      created. Table 1 illustrates the relationship between Business Scorecard Manager objects and
      events.

      Table 1: Relationship Between Business Scorecard Objects and Events

       Object           Type attribute                                                     Event

       KPI              Microsoft.PerformanceManagement.Scorecards.Client.KPI              Create

                                                                                           Update

                                                                                           Delete

       Scorecard        Microsoft.PerformanceManagement.Scorecards.Client.Scorecard        Create

                                                                                           Update

                                                                                           Delete

       Data source      Microsoft.PerformanceManagement.Scorecards.Client.DataSource       Create

                                                                                           Update

                                                                                           Delete

       Indicator        Microsoft.PerformanceManagement.Scorecards.Client.Indicator        Create

                                                                                           Update

                                                                                           Delete

       Annotation       Microsoft.PerformanceManagement.Scorecards.Client.Annotation       Create

                                                                                           Update

                                                                                           Delete
MSMQ Triggers                                     4
Example of a Business Scorecard Manager MSMQ Message
      The following is an example of a typical MSMQ message generated by Business Scorecard
      Manager:

      <?xml version="1.0" ?>
      <BpmMessage xmlns:xsd="http://www.w3.org/2001/XML Schema"
      xmlns:xsi="http://www.w3.org/2001/XML Schema-instance"
      Guid="313189e5-2f5c-4fe7-b21f-823f8646b2fb" Version="1"
      Type="Microsoft.PerformanceManagement.Scorecards.Client.Indicator"
      Action="Create" Login="Domain\UserName" Element="" />.


      The message has the following attributes:
         Guid, which is the identifier for the scorecard element.
         Version, which is the version number of the scorecard element.
         Type, which is the type of the scorecard element. (In the preceding example, the element
          type is Indicator.)
         Action, which is the action that is performed on the scorecard element.
         Login, which is the login name of the user who performed the action.
         Element, which is a serialized format of the actual element. Business Scorecard Manager
          does not store the entire element in the message queue because a Unicode message in an
          MSMQ queue cannot be greater than 2 megabytes (MB) in size.

      For more information about managing resources in MSMQ, see the article "Resource
      Management in MSMQ Applications" on MSDN® at:
      http://go.microsoft.com/fwlink/?LinkId=55318


Using MSMQ Triggers To Process Messages from a Queue
      A typical architecture for pulling messages from a message queue uses a Microsoft
      Windows® service application on the receiving end of a queue, which is constantly polling
      for new messages. When a new message arrives, the service application reads it from the
      queue and performs some action(s). There are several issues associated with using this type
      of architecture that are addressed by using MSMQ Triggers Application, which is installed
      with Microsoft Windows Server™ 2003, to ensure successful polling of Business Scorecard
      Manager message queues and retrieval of messages.
      Issue: If the Windows service application is not running, you might lose the messages that
      are in the queue.
      Solution: Because the MSMQ Triggers Application is also a Windows service, the messages
      in the queue are processed when the service is restarted.
      Issue: If there is more than one service application polling the queue, you must decide what
      service is to receive messages first.
      Solution: The components attached to rule actions will receive the message in sequential
      order when you use the MSMQ Triggers Application.
MSMQ Triggers                                5
      Issue: If the first service to receive a message deletes the message, none of the other service
      applications will receive the message.
      Solution: With the recommended architecture, a message is deleted only after the last action
      is finished.
      Issue: If a service application reads but does not delete a message, it is not clear what service
      will delete the message when all service applications have finished polling the queue.
      Solution: The last action deletes the message from the message queue when you use the
      MSMQ Triggers Application.


MSMQ Triggers
      MSMQ Triggers Application makes it possible for MSMQ to perform a specific action upon
      receipt of an incoming message in a queue. The application monitors all the queues that have
      triggers associated with them. When a message is received on a monitored queue, MSMQ
      Triggers Application uses the rules and conditions to determine what action to take. The
      action can take the form of the invocation of a method within a COM component or of
      running a standard executable.
      Triggers can take an existing COM component and invoke a specific method on the basis of
      the attributes of the message and the queue in which the message arrives.
      A trigger consists of a set of rules that are made up of conditions and actions. A single trigger
      can have many rules, and one rule can be associated with multiple triggers. Therefore, a rule
      is created independent of an actual trigger. The first stage of using a trigger involves creating
      a rule, providing the rule with a unique name and a description, and then defining the
      conditions and actions.

      Conditions
      Condition checks are performed against incoming messages to determine whether the action
      is appropriate, according to whether the condition has been met. All condition checks must
      be passed in order before an action is taken. Conditions are case sensitive.

      Actions
      Actions are taken when all of the specified conditions are met. An action can be one of the
      following:
         Invocation of a COM method in a COM DLL (or in a .NET assembly through COM
          Interop). You provide the ProgID and method name for the component. Additional
          parameters can be passed to the method call.
       Running a WIN32® executable.

      When do you use more than one trigger?
      If you have multiple triggers, they will be processed independently and possibly
      simultaneously. This works well when the sequence in which the triggers execute is not
      critical, or when one of the rules involves a long running process and other rules do not
      depend on that rule completing first.

MSMQ Triggers                                 6
      When do you use more than one rule?
      When you attach multiple rules to one trigger, MSMQ Triggers Application runs the rules
      according to the priority that you set when you attached the rules to the trigger. The
      application waits until the execution of one rule is complete before executing the next rule.
      This is helpful because all of the rules associated with a trigger are run in a strict sequence.
      You might want to set the last rule that runs to consume the MSMQ message or to send a
      notification that the trigger has run and the message has been processed.


Sample Message Parser
      This section describes how to create a message parser using the Microsoft .NET Framework.
      This component can later be called by an action in order to process a message in a queue.
      The following code sample is a .NET component that writes the contents of a message in a
      queue to a text file. This component is contained within a class library called
      MSMQXMLLog. This class library contains a ParseMessage method that parses the
      MessageBody of the message.
      Note the following when you are viewing the code sample:
         You must add the GUID, ProgId, and ComVisible attributes to make the .NET
          component aware of COM.
         The MSMQ message contains all of the attributes listed in the earlier section "Example of
          a Business Scorecard Manager Message." The .NET component makes a Web service call
          to Business Scorecard Manager server to retrieve additional information about the
          element, such as Name, Description, and so forth.
         Triggers can only call a COM component. This example makes COM-callable wrappers
          (CCWs) for the.NET component and stores these wrappers in the Global Assembly
          Cache (GAC). To generate CCWs automatically, in your project's Configuration
          Properties in Visual Studio .NET, select Register for COM Interop.

      using   System;
      using   System.Messaging;
      using   System.EnterpriseServices;
      using   System.Runtime.InteropServices;
      using   System.IO;
      using   System.Text;
      using   System.Xml;

      using Microsoft.PerformanceManagement.Scorecards.Client;

      namespace Microsoft.PerformanceManagement.Scorecards.Samples
      {
          // Contract service
          public interface ITrigger
          {
              void ParseMessage(object message);
          }
          // CLSID
          [Guid("CED4CDF9-B839-48B5-9F97-1D3FB1318719")]
          // ProgId
          [ProgId("BSM.MSMQXMLLog")]
          [ComVisible(true)]
          public class MSMQXMLLog : ServicedComponent, ITrigger

MSMQ Triggers                                 7
         {
                // COM Activated method
                [ComVisible(true)]
                public void ParseMessage(object message)
                {
                    IBpm manager;
                    string bsmServerName = "http://localhost:46786";
                    Guid guid = Guid.Empty;
                    string name = String.Empty;
                    string description = String.Empty;
                    string login = String.Empty;
                    BpmMessageAction action;
                    string type = String.Empty;

                   Kpi kpi = null;
                   Scorecard scorecard = null;
                   DataSource dataSource = null;
                   Indicator indicator = null;
                   Annotation annotation = null;

                   try
                   {
                         Message myMessage = new Message();
                         //Creating an instance of the WebService
                         manager = PmService.CreateInstance(bsmServerName + "/PmService.asmx");
                         //Get the MessageBody into a Memorystream
                         myMessage.BodyStream = new System.IO.MemoryStream((byte[])message);
                         //Specify the XmlMessageFormatter to convert the stream into a BmpMessage
      object later
                     myMessage.Formatter = new XmlMessageFormatter(new Type[]
      { typeof(BpmMessage)});
                     //Generate the BpmMessage object out of the message body
                     BpmMessage bpmMessage = (BpmMessage)myMessage.Body;
                     //Get the Guid of the message
                     guid = bpmMessage.Guid;
                     //Get the Login(Who changed?)of the message
                     login = bpmMessage.Login;
                     //Get the Action (Create/Update/Delete) on the message
                     action = bpmMessage.Action;
                     //Get the Type (Kpi/Scorecard/Annotation/Datasource/Indicator) of the
      message
                     type = bpmMessage.Type.ToString();

                         switch (type)
                         {
                             case "Microsoft.PerformanceManagement.Scorecards.Client.Kpi":
                             {
                                 // If the action is not delete then get the KPI by
                                 // calling the webservice through Client.dll
                                 if(action != BpmMessageAction.Deleted)
                                 {
                                     kpi = manager.GetKpi(guid);
                                     name = kpi.Name.Text;
                                     description = kpi.Description.Text;
                                 }
                                 // If the action is Delete as the element is already deleted from
                                 // the database just display 'N/A'
                                 else
                                 {
                                     name = "N/A";
                                     description = "N/A";;
                                 }
                                 type = "Kpi";
                                 break;
                             }
                             case "Microsoft.PerformanceManagement.Scorecards.Client.Scorecard":
MSMQ Triggers                                 8
                {
                    // If the action is not delete then get the KPI by
                    // calling the webservice through Client.dll
                    if(action != BpmMessageAction.Deleted)
                    {
                        scorecard = manager.GetScorecard(guid);
                        name = scorecard.Name.Text;
                        description = scorecard.Description.Text;
                    }
                    // If the action is Delete as the element is already deleted from
                    // the database just display 'N/A'
                    else
                    {
                        name = "N/A";
                        description = "N/A";;
                    }
                    type = "Scorecard";
                    break;
                }
                case "Microsoft.PerformanceManagement.Scorecards.Client.DataSource":
                {
                    // If the action is not delete then get the KPI by
                    // calling the webservice through Client.dll
                    if(action != BpmMessageAction.Deleted)
                    {
                        dataSource = manager.GetDataSource(guid);
                        name = dataSource.Name.Text;
                        description = dataSource.Description.Text;
                    }
                    // If the action is Delete as the element is already deleted from
                    // the database just display 'N/A'
                    else
                    {
                        name = "N/A";
                        description = "N/A";;
                    }
                    type = "DataSource";
                    break;
                }
                case "Microsoft.PerformanceManagement.Scorecards.Client.Indicator":
                {
                    // If the action is not delete then get the KPI by
                    // calling the webservice through Client.dll
                    if(action != BpmMessageAction.Deleted)
                    {
                        indicator = manager.GetIndicator(guid);
                        name = indicator.Name.Text;
                        description = indicator.Description.Text;
                    }
                    // If the action is Delete as the element is already deleted from
                    // the database just display 'N/A'
                    else
                    {
                        name = "N/A";
                        description = "N/A";;
                    }
                    type = "Indicator";
                    break;
                }
                case "Microsoft.PerformanceManagement.Scorecards.Client.Annotation":
                {
                    // If the action is not delete then get the KPI by
                    // calling the webservice through Client.dll
                    // but Annotations doesn't have any name and description
                    // and the Annotation Element contains additional info about the
                    // Scorecard and the data slices to which it belongs to
MSMQ Triggers                     9
                               if(action != BpmMessageAction.Deleted)
                               {
                                   annotation = manager.GetAnnotation(guid);
                                   name = "N/A";
                                   description = "N/A";
                               }
                               // If the action is Delete as the element is already deleted from
                               // the database just display 'N/A'
                               else
                               {
                                   name = "N/A";
                                   description = "N/A";
                               }
                               type = "Annotation";
                               break;
                         }
                     }
                     //Call the AddReport to log into a XML File
                     AddToReport(type, name,
      description ,guid.ToString(),action.ToString() ,login);
                 }
                 catch(Exception ex)
                 {
                     LogException(ex);
                 }
             }

                [ComVisible(false)]
                void LogException(Exception ex)
                {
                    TextWriter errorOutput = null;
                    try
                    {
                        //If an error occurs try to log into a error log
                        string errorfile = @"C:\MSMQXMLLog_Error.log";
                        if (!File.Exists(errorfile))
                            errorOutput = File.CreateText(errorfile);
                        else
                            errorOutput = File.AppendText(errorfile);

                       errorOutput.WriteLine(ex.Message);
                       errorOutput.WriteLine(ex.StackTrace);
                       errorOutput.Close();
                   }
                   catch
                   {
                   }
                   finally
                   {
                       if(errorOutput != null)
                           errorOutput.Close();
                   }
             }
             /// <summary>
             /// Add the Message to an XML file.
             /// </summary>
             /// <param name="Type"></param>
             /// <param name="Name"></param>
             /// <param name="Description"></param>
             /// <param name="Guid"></param>
             /// <param name="Action"></param>
             /// <param name="Login"></param>
             [ComVisible(false)]
             void AddToReport(string Type, string Name, string Description, string Guid, string
      Action, string Login )
             {
MSMQ Triggers                                10
                 try
                 {
                       string filename = @"C:\MSMQXMLLog.xml";

                       XmlDocument xmlDoc = new XmlDocument();

                       try
                       {
                         xmlDoc.Load(filename);
                     }
                     catch(System.IO.FileNotFoundException)
                     {
                         //if file is not found, create a new xml file
                         XmlTextWriter xmlWriter = new XmlTextWriter(filename,
      System.Text.Encoding.UTF8);
                         xmlWriter.Formatting = Formatting.Indented;
                         xmlWriter.WriteProcessingInstruction("xml", "version='1.0'
      encoding='UTF-8'");
                         xmlWriter.WriteStartElement("Elements");
                         xmlWriter.Close();
                         xmlDoc.Load(filename);
                     }

                       XmlNode root = xmlDoc.DocumentElement;
                       //Creating a new "Element" as child node
                       //Create "Type & Name & Description & Guid & Action & Login" nodes
                       XmlElement childNode = xmlDoc.CreateElement("Element");
                       XmlElement nodeType = xmlDoc.CreateElement("Type");
                       XmlElement nodeName = xmlDoc.CreateElement("Name");
                       XmlElement nodeDescription = xmlDoc.CreateElement("Description");
                       XmlElement nodeGuid = xmlDoc.CreateElement("Guid");
                       XmlElement nodeAction = xmlDoc.CreateElement("Action");
                       XmlElement nodeLogin = xmlDoc.CreateElement("Login");

                       //Assigning data to the above added nodes
                       nodeType.InnerText = Type;
                       nodeName.InnerText = Name;
                       nodeDescription.InnerText= Description;
                       nodeGuid.InnerText = Guid;
                       nodeAction.InnerText = Action;
                       nodeLogin.InnerText = Login;

                     //Appending the "Type & Name & Description & Guid & Action & Login" nodes
      to the "Element" node
                     childNode.AppendChild(nodeType);
                     childNode.AppendChild(nodeName);
                     childNode.AppendChild(nodeDescription);
                     childNode.AppendChild(nodeGuid);
                     childNode.AppendChild(nodeAction);
                     childNode.AppendChild(nodeLogin);
                     //Insert the new Element node at the end of the xml file
                     xmlDoc.DocumentElement.InsertAfter(childNode,
      xmlDoc.DocumentElement.LastChild);
                     // Save the file
                     xmlDoc.Save(filename);
                 }
                 catch(Exception ex)
                 {
                     LogException(ex);
                 }
             }
          }
      }




MSMQ Triggers                               11
      To add the .NET component to the GAC
      1.   Generate a strong name and use the gacutil tool to insert the assembly in the GAC.
      2.   Use the following .NET command prompt to generate a strong name key file in your project
           directory.

           sn –k msmqKey.snk


      3.   In the AssemblyInfo.cs file, you must add the value ..\\..\\msmqkey.snk to AssemblyKeyFile,
           as shown in the following example:

           [assembly: AssemblyKeyFile("..\\..\\msmqkey.snk ")]


      4.   Build the assembly. This creates MSMQXMLLog.dll.
      5.   Use the following.NET command prompt and the gacutil tool to place the MSMQXMLLog.dll
           into the GAC:

           gacutil –i MSMQXMLLog.dll



Creating MSMQ Queues, Rules, and Triggers
      Before you can create queues, rules, or triggers, you must install MSMQ and MSMQ Triggers
      Application and enable MSMQ on the Business Scorecard Manager server.
      To enable MSMQ on the Business Scorecard Manager server
      1.   Open Business Scorecard Builder.
      2.   On the Tools menu, click Server Administration.
      3.   In the Server Administration window, in the navigation pane, click General Settings.
           If General Settings is not available, go to the right pane of the window, and click Connect to
           connect to the server.
      4.   In the right pane of the window, select the Microsoft Message Service queue (MsmQueue)
           enabled check box.
      5.   In the Type Microsoft Message Service queue (MsmQueue) name box, type the name of the
           message queue, and then click Close to close the dialog box.

      To create a MSMQ queue on the Business Scorecard Manager server
      6.   In Windows Server 2003, click Start, point to Control Panel, point to Administrative Tools,
           and then click Computer Management.
      7.   In the navigation pane, under Computer Management, expand Services and Applications,
           expand Message Queuing,
      8.   Right-click the Public Queues node, point to New, and then click Public Queue.
      9.   In the New Object – Public Object dialog box, in the Queue name box, type the name of the
           queue that you entered in step 5 of the procedure "To enable MSMQ on the Business
           Scorecard Manager server”.
      10. Make sure the Transactional check box is clear, and then click OK to close the dialog box.


MSMQ Triggers                                   12
      To create a rule
      1.   In Windows Server 2003, click Start, point to Control Panel, point to Administrative Tools,
           and then click Computer Management.
      2.   In the navigation pane, under Computer Management, expand Services and Applications,
           expand Message Queuing, and then expand Triggers.
      3.   Under Triggers, right-click Rules, point to New, and then click Rule.
      4.   In the New Rule dialog box, in the Rule name box, type LogInXML.
      5.   In the Rule description box, type a description, and then click Next.
      6.   Under New condition, in the Condition drop-down list, select Message label contains.
      7.   In the Filter value/string box, type BpmMessage.
      8.   Click Add to add the condition to the Condition list box, and then click Next.
      9.   Under COM component invocation, click Invoke COM component.
      10. In the Component ProgID box, type BSM.MSMQXMLLog.
      11. In the Method name box, type ParseMessage.
      12. Click Parameters.
           This opens the Invocation Parameters dialog box.
      13. In the Parameter drop-down list, select Message body (as variant).
      14. Click Add to add the rule to the Invocation Parameters list box, and then click OK to close
          the dialog box.
      15. Click Finish to complete the creation of your new rule.

           Rules must be attached to triggers in order to work. The following procedure describes
           how to create a trigger and then attach a rule to it.

      To create a trigger and attach a rule to it
      1.   On the desktop, click Start, point to Control Panel, point to Administrative Tools, and then
           click Computer Management.
      2.   In the navigation pane, under Computer Management, navigate to the node for the Business
           Scorecard Manager message queue.
           This is the location that you specified in Business Scorecard Builder as the location where
           messages are to be posted.
      3.   Expand the node for the message queue, right-click Triggers, and then click New.
      4.   Click Trigger to open the New Trigger wizard.
      5.   In the Trigger name box, type BpmMessageProcess.
      6.   Under Message processing type, click Retrieval if it has not already been selected.
      7.   Select the Enabled check box, and make sure the Serialized check box is clear.
      8.   Click Next.
           The rule called LogInXML that you created in the previous procedure should appear in the
           Rules box.

MSMQ Triggers                                       13
      9.   Select LogInXML, and then click Attach to attach this rule to the trigger.
      10. Click Finish.
           Your new trigger is complete.

      Figure 2 shows the .xml file that is generated from the two components.




      Figure 2
      Sample .xml file

      If you want to create listeners, we recommend that you add them as rules for a single trigger
      so that all of the components receive the message before the message is deleted from the
      message queue. One caveat to this recommendation is that if one rule requires a lot of time to
      process, all remaining rules must wait for it to complete before they can be processed.

MSMQ Triggers                                  14

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:137
posted:2/22/2008
language:English
pages:14