{"type":"doc","content":[{"type":"paragraph","content":[{"text":"EngageIP contains core features for ingesting data that details the consumption of measurable resources. Usage data records (UDR) can enter the EngageIP system in two ways:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Real Time API","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Feed files","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This section will discuss the feed files and how to ingest the data within these feeds. Rating of data from feeds is not done in real time but is instead performed at regular intervals (typically every 10 seconds).","type":"text"}]},{"type":"paragraph","content":[{"text":"A feed is usage data of a specific type that is contained within one or more files on the local EngageIP file system. The format of the feed files can be based on the EngageIP standard for a UDR record or any format the customer chooses. Most customers will have a format that is not based on the EngageIP UDR record.","type":"text"}]},{"type":"paragraph","content":[{"text":"The start of the feed workflow is the EngageIPRatingService. EngageIPRatingService is a Windows Service by the name \"EngageIP Rating Service\" which is installed and configured as part of deploying a customer instance of EngageIP. When EngageIPRatingService runs it invokes the UDR Rating Engine to perform the majority of the business logic.","type":"text"}]},{"type":"paragraph","content":[{"text":"Within the UDR Rating Engine Rate() method the following sequence of steps happens:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Rerating will pick up reconfigurations in buckets that might impact this rating cycle due to UserPackage additions, UserPackage cancellations, or rate changes","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Iterate through all configured and enabled feeds","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Setup each feed as a data source. A data source is a custom code implementation of the IUDRDataSource C# Interface","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Initialize the data source using the custom code implementation of the Init method in the IUDRDataSource C# Interface","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each line from the data source feed file is retrieved by calling the data source implementation of the IUDRDataSource Read method","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The data source Mediate() method is executed to transform the feed data into EngageIP UDR records. The Mediate method is a custom code implementation of the IUDRDataSource C# Interface","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Additional mediation activities might need to be performed","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The UDR Rating Engine iterates through all configured preprocessors and executes the Process() method on them. Each preprocessor is a custom code implementation of the C# IUDRProcessor Interface","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A final data linkage is needed to match up the incoming usage data record with the information previously configured in the EngageIP database. The database table UDRUserIdentifierHistory (UUIH) is queried and added to the UDR record. The UUIH data is added to the database prior to the usage data ingestion using business logic in a custom code implementation derivation of the C# UUIHWorkflowBase (a derived implementation of the C# IAction Interface). This custom code module frequently implements other C# Interfaces as well. For example, IOverrideuserService, IUseUserServiceAttributeProfileAnswer, and IUseUserAttributeProfileAnswer","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The next custom code integration point is the post processors. Similar to the preprocessors above UDR Rating Engine iterates through all configured post processors and executes them. Each Post processor is a custom code implementation of the C# IUDRProcessor Interface","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Later in the workflow the UDR Rating Engine iterates through each configured custom code implementations of the C# IUDRProcessorInUDRWriter Interface and executes the Process() method on them","type":"text"}]}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"UDR records can be extended with additional columns to meet a customer’s needs. In the method Logisense.Boss.Logic.CustomCodeInstallerHelper.EnsureCustomFieldExists() there is a call to Logisense.Boss.Logic.Core.UDRCustomField.Create(). This Create method executes the UDRCustomField base class Create() method which adds records to the UDRCustomField table while the derived class Create() method adds the corresponding changes to the UDR table:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add a column to UDR","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add an index on the new column in UDR","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This logic is commonly inside the Install() method in the custom code which is implementing the C# ICustomCodeInstaller Interface.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Interfaces","type":"text"}]},{"type":"paragraph","content":[{"text":"The following interfaces are available to be used:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"IUDRDataSource - Used to implement a mediation script for rating","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"IUDRProcessor - Used to insert custom code into the rating workflow","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"IUDRProcessorInUDRWriter - Used to insert custom code into the rating workflow within the UDRWriter process","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"IUDRReratingProcessor - Used to insert custom code into the re-rating workflow","type":"text"}]}]}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"text":"public interface IUDRDataSource {\n\tstring Name { get; }\n\n\t///

\n\t/// Called when the rating engine is starting up. \n\t///

\n\t/// Passed from UDRFeed.DataSourceDetails\n\t/// Maps UDRClass names to their database ID\n\tvoid Init(UDRFeed feed, Dictionary udrclasses);\n\n\t///

\n\t/// Reads a single UDR from the data source\n\t///

\n\t/// A string array that contains the raw field data. This will be passed to the Mediate function later. If there are no more records an empty array should be returned.\n\tstring[] Read();\n\n\t///

\n\t/// Called by the rating engine to mediate a single record.\n\t///

\n\t/// The raw fields of the record\n\t/// A UDR class with the appropriate fields filled in\n\tLogisense.Boss.Logic.Core.UDR Mediate(string[] rawFields, ref Dictionary ratingContext);\n\n\t///

\n\t/// Called when the current rating run is complete. Any cleanup should be done here (closing files, etc)\n\t///

\n\tvoid Close();\n}\n\npublic interface IUDRProcessor {\n\tstring Name { get; }\n\tstring Description { get; }\n\t///

\n\t/// Indicates whether this processor should be run pre- or post- rating.\n\t///

\n\tUDRProcessorType Type { get; }\n\n\t///

\n\t/// Process a UDR Record\n\t///

\n\t/// The UDR record\n\t/// False to halt processing of the UDR (ie drop it), true otherwise\n\tbool Process(Logisense.Boss.Logic.Core.UDR udr, ref Dictionary ratingContext);\n}\n\n/*\n* WriteUDR must be called within a transaction for the following assumption to hold\n* otherwise UDRBiller.Amount would suffice.\n* 1. WriteUDR calls are currently wrapped in a transaction\n* 2. WriteUDR updates the UDRBiller.Amount\n* 3. WriteUDR calls IUDRProcessorInUDRWriter\n* 4. The transaction is not finished when WriteUDR exits so the updated UDRBiller has not been persisted\n* 5. Thus to get the most up to date usage amount the UDRBiller.Amount and UDR.Amount must be added together\n*/\npublic interface IUDRProcessorInUDRWriter\n{\n\tstring Name { get; }\n\tstring Description { get; }\n\t///

\n\t/// Indicates that this process is run InUDRWriter.\n\t///

\n\tUDRProcessorType Type { get; }\n\n\t///

\n\t/// Process a UDR Record After Bucketing\n\t///

\n\t/// The UDR record\n\t/// Parameters provided from rating\n\t/// False to halt processing of the UDR (ie drop it), true otherwise\n\tbool Process(Logisense.Boss.Logic.Core.UDR udr, UDRWriterProcessorParameters udrWriterProcessorParameters);\n\n\tvoid BulkUDRWriteComplete(bool success);\n\tvoid IndividualUDRWriteComplete(bool success);\n}\n\n///

\n/// Triggers actions that need to happen when a UDRBiller is to be re-rated\n///

\npublic interface IUDRReratingProcessor\n{\n\tstring Name { get; }\n\tstring Description { get; }\n\tvoid Process(ReratingProcessorData data);\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Mediation and Rating","type":"text"}]},{"type":"paragraph","content":[{"text":"The following is an example implementation of the usage and rating customization touch points. In the first class, Installer, we can see the implementation of the ICustomCodeInstaller interface. It is doing some integrity checks as part of its initialization upon install. The second class, GenericOccurenceDataSource, is derived from the AbstractFileParsingDataSource class. This class does the core business logic inside the Mediate method. Mediate is responsible for mapping and modify fields from the input data rows into database UDR table rows. In this example there is very little modification needed to map the fields from the input to the UDR table. The key field that is needed later in the rating cycle is the UDR.BillingIdentifier. This is highlighted in bold in the code snipit below. A UDR.Billingidentifier value is used by the rating engine to pull a matching record in the Identifier column on the database UDRUserIdentifierHistory table to perform its rating calculations of this specific usage record. In this example the value in BillingIdentifier is the customer's phone number. All usage records for this customer will have their phone number in the usage data being ingested by EngageIP.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"text":"public class Installer : Logisense.Boss.Logic.Core.ICustomCodeInstaller {\n public void Install(int ownerID) {\n Owner owner = Owner.GetByID(ownerID);\n\n EnsureClassExists(\"Occurrences-Geo\", \"GeoTree\", owner, UDRUnitTypeID.Occurrences);\n EnsureClassExists(\"Volume-Geo\", \"GeoTree\", owner, UDRUnitTypeID.Data_KiB_MiB_GiB);\n EnsureClassExists(\"Occurrences-Class\", \"Class\", owner, UDRUnitTypeID.Occurrences);\n EnsureClassExists(\"Volume-Class\", \"Class\", owner, UDRUnitTypeID.Data_KiB_MiB_GiB);\n }\n\n private static void EnsureClassExists(string className, string rater, Owner owner, int unitTypeID) {\n if (owner.SearchUDRClassByName(className).Length == 0) {\n UDRClass ld = UDRClass.GetNew();\n ld.Name = className;\n ld.OwnerID = owner.ID;\n ld.UDRRater = rater;\n ld.UDRUnitTypeID = unitTypeID;\n ld.Create();\n }\n }\n}\n\npublic class GenericOccurenceDataSource : AbstractFileParsingDataSource, IUDRDataSource {\n protected SHA1CryptoServiceProvider _cryptoTransformSHA1 = new SHA1CryptoServiceProvider();\n protected Dictionary _countryCache = null;\n\n public GenericOccurenceDataSource() : base(new string[] { \"transactionId\" }, new string[] { \",\" }) {\n }\n\n public override string Name {\n get { return \"Generic Occurrence-Based\"; }\n }\n\n public override Logic.Core.UDR Mediate(string[] rawFields, ref Dictionary ratingContext) {\n var urep = System.Runtime.Remoting.Messaging.CallContext.GetData(\"UDRRatingEngineProcess\") as UDRRatingEngineProcess;\n\n\t//The follow is an example of the input format being mapped\n //0,555-123-4567,2,3,555-111-2222,2012-12-14 23:59:59.000 ,IMSI-3027 ,MT ,1 ,NULL \n var udr = UDR.GetNew() as Logic.Core.UDR;\n udr.Date = DateTime.Parse(rawFields[5]);\n udr.ImportedValue = Convert.ToInt64(Convert.ToDouble(rawFields[3]));\n udr.Value = udr.ImportedValue;\n udr.ValueActual = udr.ImportedValue;\n udr.Cost = 0;\n udr.UDRClassID = urep.GetCachedUDRClass(rawFields[2]).ID;\n udr.OriginatingIdentifier = rawFields[1];\n udr.TerminatingIdentifier = rawFields[4];\n udr.BillingIdentifier = rawFields[1];\n udr.UniquenessIdentifier = BitConverter.ToString(_cryptoTransformSHA1.ComputeHash(Encoding.UTF8.GetBytes(String.Join(\",\", rawFields)))).Replace(\"-\", \"\");\n\n return udr;\n }\n}\n","type":"text"}]},{"type":"paragraph","content":[{"text":"With incoming data being mediated correctly into EngageIP UDR records the next step is to see how it gets used during the rating process. The Rating Engine uses the UDR.BillingIdentifier to look up information in UDRUserIdentifierHistory table based on the values in the Identifier column. A matching row will contain several useful pieces of information:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Identifier - the value of the matching UDR.BillingIdentifier","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"UserID - the EngageIP user ID associated with this row","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Start and end dates for the usage record","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Foreign keys to associated records in other tables for Packages, Services and Rate Plans","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In this example the UDRUserIdentifierHistory.Identifier is \"555-123-4567\" which matches the UDR.BillingIdentifier value in the commented out sample line in the Mediate method above. This value was configured in EngageIP using a required Profile Question when the user account was created and assigned a Package. When an account is created and assigned a Package that contains a Service with a Profile Question a value must be entered. In this example the Profile Question would be something like this, \"What is the Phone Number for this account?\". This value gets save in the ProfileAnswer database table and is referenced by UserServiceAttributeProfileAnswer.ProfileAnswerID. From this table the Service and Package can be retrieved and the appropriate Rate Plan determined.","type":"text"}]},{"type":"paragraph","content":[{"text":"The value in UDRUserIdentifierHistory.Identifier is not set by EngageIP core code. It is set using a custom code implementation of a C# IAction Interface. A comprehensive solution would include and IAction.EventCode list to detect new account creations, profile answer creations, rate plan changes and anything else that might impact the database records for UDRUserIdentifierHistory. Our simple example is subscribed to events based on the creation or updating of Profile Answers. The EventCode string is \"ProfileAnswer.Create,ProfileAnswer.Update\".","type":"text"}]},{"type":"paragraph","content":[{"text":"The following is a sample custom code file that takes a profile answer create or update and creates/updates the UDRUserIdentifierHistory table for the account. Inside the ScriptContext instance will be a set of keys. The value for each key can be used to operate on the specific record that has changed in the database. In this example it is the phone number value stored in the ProfileAnswer table row.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"csharp"},"content":[{"text":"using System.Data;\nusing Logisense.Boss.Logic;\nusing Logisense.Boss.Logic.DomainModel;\nusing System;\nusing System.Collections.Generic;\n\nnamespace Logisense.Boss.CustomScripts.Examples\n{\n public class SimpleUUIH : IAction\n {\n public string Name { get { return \"UDRUserIdentifierHistory Update Workflow\"; } }\n public string Description { get { return \"UDRUserIdentifierHistory Update Workflow\"; } }\n public string EventCode { get { return \"ProfileAnswer.Create,ProfileAnswer.Update\"; } }\n public int OwnerID\n {\n get { return 1; }\n set { }\n }\n\n private const string PROFILEANSWERID = \"ProfileAnswerID\"; //example of a key in a ScriptContext instance\n\n public void Run(ScriptContext context)\n {\n if (context.ContainsKey(PROFILEANSWERID))\n {\n ProfileAnswer profileAnswer = ProfileAnswer.GetByID(Int32.Parse(context[PROFILEANSWERID].ToString()));\n\n IdentifierDetails identifierDetails = null;\n if (GetIdentifierAndUserForUserServiceAttributeProfileAnswer(ref identifierDetails, profileAnswer))\n {\n UserService userService = identifierDetails.IdentifierUserService;\n User user = User.GetByID(userService.UserID);\n RatePlanDetails ratePlan = GetRatePlanForUUIHUserServiceEntry(userService);\n\n UDRUserIdentifierHistory udrUsageIdentifierHistory = UDRUserIdentifierHistory.GetNew();\n udrUsageIdentifierHistory.UserID = user.ID;\n udrUsageIdentifierHistory.Identifier = identifierDetails.Identifier;\n udrUsageIdentifierHistory.OwnerID = User.GetByID(user.ID).OwnerID;\n udrUsageIdentifierHistory.End = DateTime.MaxValue;\n udrUsageIdentifierHistory.Parent_UserID = user.GetUserParent().Parent_UserID;\n udrUsageIdentifierHistory.UserServiceID = userService.ID;\n udrUsageIdentifierHistory.UDRRatePlanID = ratePlan.CurrentUDRRatePlan.ID;\n udrUsageIdentifierHistory.RatePlan_ServiceID = ratePlan.ServiceID;\n udrUsageIdentifierHistory.RatePlan_UserPackageID = ratePlan.UserPackageID;\n udrUsageIdentifierHistory.IdentifierSource = identifierDetails.IdentifierSource;\n udrUsageIdentifierHistory.Start = DateTime.Now;;\n udrUsageIdentifierHistory.Create();\n }\n }\n }\n\n private bool GetIdentifierAndUserForUserServiceAttributeProfileAnswer(ref IdentifierDetails identifier,\n ProfileAnswer profileAnswer)\n {\n UserServiceAttributeProfileAnswer userServiceAttributeProfileAnswer =\n GetUserServiceAttributeProfileAnswer(profileAnswer);\n if (userServiceAttributeProfileAnswer == null)\n {\n return false;\n }\n\n identifier = new IdentifierDetails(profileAnswer.Value, profileAnswer.GetProfileQuestion().Name,\n userServiceAttributeProfileAnswer.GetUserService());\n\n return true;\n }\n\n private UserServiceAttributeProfileAnswer GetUserServiceAttributeProfileAnswer(ProfileAnswer pa)\n {\n UserServiceAttributeProfileAnswer[] attributeProfileAnswers =\n pa.GetUserServiceAttributeProfileAnswerCollection();\n\n if (attributeProfileAnswers == null || attributeProfileAnswers.Length == 0)\n return null; //Not connected to a Userservice must not be one we are looking for\n\n return (Logic.Core.UserServiceAttributeProfileAnswer) attributeProfileAnswers[0];\n }\n\n private RatePlanDetails GetRatePlanForUUIHUserServiceEntry(UserService userService)\n {\n UserPackage userPackage = UserPackage.GetByID(userService.UserPackageID);\n UserPackageAttributeUDRRatePlan[] userPackageAttributeUDRRatePlans =\n userPackage.GetUserPackageAttributeUDRRatePlanCollection();\n\n //Should never be more than one record but in case there are multiple records choose the first one\n if (userPackageAttributeUDRRatePlans.Length > 0) \n {\n UserPackageAttributeUDRRatePlan userPackageAttributeUDRRatePlan = userPackageAttributeUDRRatePlans[0];\n return new RatePlanDetails(UDRRatePlan.GetByID(userPackageAttributeUDRRatePlan.UDRRatePlanID),\n userPackageAttributeUDRRatePlan.ServiceID, userService.UserPackageID);\n }\n\n Package package = Package.GetByID(userPackage.PackageID);\n PackageAttributeUDRRatePlan[] packageAttributeUDRRatePlans =\n package.GetPackageAttributeUDRRatePlanCollection();\n foreach (PackageAttributeUDRRatePlan packageAttributeUDRRatePlan in packageAttributeUDRRatePlans)\n {\n if (PackageServiceConnector.GetByID(packageAttributeUDRRatePlan.PackageServiceConnectorID).ServiceID ==\n userService.ServiceID)\n {\n return new RatePlanDetails(UDRRatePlan.GetByID(packageAttributeUDRRatePlan.UDRRatePlanID),\n userService.ServiceID, userService.UserPackageID);\n }\n }\n\n //Should never be more than one record but in case there are multiple records choose the first one\n if (packageAttributeUDRRatePlans.Length > 0) \n {\n PackageAttributeUDRRatePlan packageAttributeUDRRatePlan = packageAttributeUDRRatePlans[0];\n return new RatePlanDetails(UDRRatePlan.GetByID(packageAttributeUDRRatePlan.UDRRatePlanID),\n PackageServiceConnector.GetByID(packageAttributeUDRRatePlan.PackageServiceConnectorID).ServiceID,\n userService.UserPackageID);\n }\n\n return null;\n }\n }\n\n public class IdentifierDetails\n {\n public readonly string Identifier;\n public readonly string IdentifierSource;\n public readonly UserService IdentifierUserService;\n\n public IdentifierDetails(string identifier, string identifierSource, UserService identifierUserService)\n {\n Identifier = identifier;\n IdentifierSource = identifierSource;\n IdentifierUserService = identifierUserService;\n }\n }\n\n public class RatePlanDetails\n {\n public UDRRatePlan CurrentUDRRatePlan;\n public int ServiceID;\n public int UserPackageID;\n\n public RatePlanDetails(UDRRatePlan udrRatePlan, int serviceID, int userPackageID)\n {\n CurrentUDRRatePlan = udrRatePlan;\n ServiceID = serviceID;\n UserPackageID = userPackageID;\n }\n }\n}","type":"text"}]},{"type":"paragraph"}],"version":1}

Browser not supported