Restructure for Docsy theme

content/docs/NAVPatterns/patterns/blocked-entity/_index.md

@@ -0,0 +1,104 @@
++++
+title = "Blocked Entity"
+weight = 270
++++
+_Originally by Abhishek Ghosh at Microsoft Development Center Copenhagen_ 
+
+## Abstract
+
+The Blocked Entity is used when it is required to stop transactions for an entity (mostly master data), temporarily or permanently.
+
+[![ ][image0]][anchor0]
+
+## Description
+
+To block entities through metadata, read this pattern. To do the same thing through data, read [Data Driven Blocked Entity pattern][anchor1].  
+
+The business entity holds a state that controls if a given transaction is allowed. The state is used by the logic controlling transactions.  The change of state could either be temporary or permanent.
+
+An example of a temporary halt is when a retail chain selling items has received lot of complaints about an item, and the company wants to stop all transactions, both purchase and sale, with that item until the dealer has clarified the issue with his supplier and possibly received a replacement for the defective stock. Another common example is during counting the physical inventory using cycle counting where the counting is done in one section of a warehouse at a time, so that the regular operations can continue in the other parts of the warehouse. In these situations, it is necessary to block all transactions, such as picks and put-aways, for a bin while warehouse counting is in progress for that bin.
+
+In contrast, a permanent halt to transactions could be required when an item has become obsolete (or is about to become obsolete), and the company wants to stop further purchase or sale of the item. However, the company wants to maintain the transaction history of the item and, therefore, does not want to delete the item record.
+
+A simple design implementation of such requirements in Microsoft Dynamics NAV is to add a Blocked field in the entity table (and on the associated page). The implementation takes this state into the logic and checks for the value of this field in related transactions. For most simple scenarios, it is sufficient to have two states on the Blocked field, specifying whether it is allowed to perform transactions for the entity or not.
+
+In certain situations, however, there could be different levels of blocking. For example, the company could block all sales to a customer that has overdue payments, and the company does not want to allow transactions with this customer until the payments are received. In other situations, the customer may have raised objections about an invoice, and the company has decided not to generate new invoices for the customer until the issue has been resolved. However, the company does want to continue shipping goods to the customer so as not to impact the customer's operations. In these scenarios, it may be necessary to have multiple states on the Blocked field depending on the level of restriction that is needed.
+
+## Usage
+
+As mentioned in the previous section, there are two implementations depending on business requirements: The 2-state Boolean field for simple implementations and the multi-state option field for more complex requirements. The implementation flow is similar for both patterns, except how the validation is implemented. The following discusses the two scenarios one by one.
+
+### Boolean Implementation
+
+Add a Boolean field named Blocked in the table.
+
+In the relevant logic, add a condition to check the status of the Blocked flag. The cheapest way is to use a TESTFIELD:
+
+```AL
+<rec variable\>.TESTFIELD(Blocked,FALSE);
+```
+
+Alternatively, you can throw a custom error message. However, you should only do that if the default error message thrown by TESTFIELD is not sufficient.
+
+### Option-Field Implementation
+
+Add an option field named Blocked in the table. The option values will reflect the different blocked states required by the company.
+
+Add this field on the card page (or on the List page if the entity does not have a card). As with the Boolean implementation, the convention is to add this field in the right-hand column in the General FastTab of the card page.
+
+Implement a function in the table that takes the transaction context as input and evaluates the Blocked field to decide whether the transaction should be allowed or not. Optionally, the function can be responsible for notifying the user and bubble up an error message straight away.
+
+Note: the option field assumes that only one of the multiple options can be active at a time. In other words, the options should be mutually exclusive. 
+
+How not to use the option field in this case: if we want to block an item from sale and/or purchase, the 4 combined options would be **Block none** | **Block Sales** | **Block Purchases** | **Block Sales and Purchases**. This doesn't scale, because if now we need to block another transaction, the number of option would grow too fast. In this situations, it is better to use two Boolean fields: **Blocked Sale**: **true|false** and **Blocked Purchase: true|false**.
+
+A good example of usage would be for varying the behavior depending on the chosen option, for example by displaying a different error message depending on the reason an Item is blocked. In this case we can have the item **Not Blocked** | **Blocked due to defect** | **Blocked waiting for approval**, etc. 
+
+## NAV Specific Example
+
+### Boolean Implementation
+
+[![ ][image1]][anchor2]
+
+An example of the Boolean implementation on the Item card.
+
+In codeunit 22 -- Item Jnl.-Post Line, the following lines of code have implemented a check based on the value of the Blocked field:
+
+```AL
+IF NOT CalledFromAdjustment THEN
+    Item.TESTFIELD(Blocked,FALSE);
+```
+### Option-Field Implementation
+
+[![ ][image2]][anchor3]
+
+An example of the option field implementation on the Customer card.
+
+The CheckBlockedCustOnDocs and CheckBlockedCustOnJnls functions in the Customer table are responsible for validating the Blocked state with respect to the input document type. These functions are invoked in several areas, such as posting routines, where a status check on the Blocked field is required. This is a good practice where the Blocked implementation gets more complex, as this encourages reuse and ensures uniformity of implementation.
+
+## NAV Usages
+
+Entities where the Blocked Entity has been implemented include:
+
+* Item
+* G/L Account
+* Customer
+* Vendor
+* Bin  
+
+## Related Topics
+
+The [Released Entity][anchor4].
+
+{{< youtube O2R-fTSup1o >}}
+
+[anchor0]: 2260.BlockedEntityPattern.png
+[anchor1]: /navpatterns/1-patterns/blocked-entity/data-driven-blocked-entity/
+[anchor2]: 8637.BlockedEntityPattern_5F00_5F00_5F00_Boolean.png
+[anchor3]: 3056.BlockedEntityPattern_5F00_5F00_5F00_Option.png
+[anchor4]: /navpatterns/1-patterns/released-entity/
+
+
+[image0]: 2260.BlockedEntityPattern.png
+[image1]: 8637.BlockedEntityPattern_5F00_5F00_5F00_Boolean.png
+[image2]: 3056.BlockedEntityPattern_5F00_5F00_5F00_Option.png

content/docs/NAVPatterns/patterns/blocked-entity/data-driven-blocked-entity/index.md

@@ -0,0 +1,111 @@
++++
+title = "Data Driven Blocked Entity"
+weight = 470
++++
+_Written by Bogdan Andrei Sturzoiu, at Microsoft Development Center Copenhagen_
+
+## Abstract
+
+This pattern implements a generic mechanism for dynamically restricting and allowing usage of a record by the business process administrator. 
+
+## Problem
+
+A NAV record can be used in a number of functionalities across the app. There are situations, however, when the administrator wants to restrict the consumption of such a record, as well as lift the restriction when it is no longer relevant.
+
+For example, a new customer record should not be used for posting documents until it is approved by the relevant approver.
+
+We could solve this by using the [Blocked Entity pattern][anchor1], but it requires database schema changes, which have an upgrade impact.
+
+The blocked entity pattern involves:
+
+1. Adding a "blocked" status field on the record (either a Boolean or in the more advanced cases, an option field refining the usage).
+2. Adding specific code for the record in every place where the restriction needs to be enforced.
+
+In contrast, the Data-driven Blocked Entity pattern involves adding a new record (data change) to mark the restriction, instead of adding a new field (metadata change).
+
+## Solution
+
+This pattern describes a generic mechanism of adding and lifting restrictions for any type of record.
+
+The restriction mechanism has the following elements:
+
+1. Adding a restriction record for a specific reason (e.g. the record requires approval), which will act as a surrogate key (unique identifier) for the restricted record. This can be implemented through a workflow response, or directly, by calling the Restriction Management codeunit function.
+2. Lifting the restriction when it is no longer necessary. Again, this can be done using a workflow response or directly by calling the dedicated function.
+3. Consuming the restriction in the places of interest for a specific purpose. This is an application feature that requires a call to the Restriction Management codeunit to check for restrictions.
+
+Currently, the restrictions are record-based and type-less. They act as simple tokens, and they have:
+
+* A reason (e.g. the record requires approval)
+* A purpose (e.g. the record cannot be posted).
+
+You must make sure to differentiate between the reason and the purpose. That is because the restriction can only be added once per record, but consumed in multiple places.
+
+
+
+## Example
+
+For example, we want to restrict posting Gen. Journal Lines if a customer has not been added in Account No. field.
+
+For this, the following components are needed:
+
+1. When a Gen. Journal Line is inserted, call RestrictRecordUsage in COD1550, either directly in the trigger or using an event subscriber.
+2. When you validate a Customer No. as Account no. and Customer as Account Type, lift the restrictions by calling AllowRecordUsage in COD1550\.
+3. The consumption of the restriction at posting is already implemented as an event in TAB81, OnCheckGenJournalLinePostRestrictions. No further action necessary.
+
+## NAV Usage
+
+All the approval workflows include a response that restricts usage of a record, and then, at the end of an approval loop, a response that allows the usage again by lifting the restriction. See responses "Add record restriction" and "Remove record restriction" implemented in COD1521\.[  
+][anchor2]
+
+The code behind the "Add record restriction" workflow response:
+
+```AL
+RecRef.GETTABLE(Variant);
+Workflow.GET(WorkflowStepInstance."Workflow Code");
+RecordRestrictionMgt.RestrictRecordUsage(RecRef.RECORDID,STRSUBSTNO(RestrictUsageDetailsTxt,Workflow.Code,Workflow.Description));
+```
+
+The code behind the "Remove record restriction" response:
+
+```AL
+RecRef.GETTABLE(Variant);
+CASE RecRef.NUMBER OF
+    DATABASE::"Approval Entry":
+        BEGIN
+            RecordRestrictionMgt.AllowRecordUsage(RecRef.RECORDID);
+            RecRef.SETTABLE(ApprovalEntry);
+            RecRef.GET(ApprovalEntry."Record ID to Approve");
+            AllowRecordUsage(RecRef);
+        END;
+    DATABASE::"Gen. Journal Batch":
+        BEGIN
+            RecRef.SETTABLE(GenJournalBatch);
+            RecordRestrictionMgt.AllowGenJournalBatchUsage(GenJournalBatch);
+        END
+    ELSE
+        RecordRestrictionMgt.AllowRecordUsage(RecRef.RECORDID);
+END;
+```
+
+Notice how lifting a restriction for a Gen. Journal Batch involves lifting all the restrictions for the individual journal lines in the batch (hence the special branching of the code).
+
+
+
+## Consequences
+
+Currently, there can only be one restriction per record. There are no restriction types.
+
+In the future, a type field should be added to the restriction table, to allow adding restrictions for different purposes, and to refine their consumption. For example, a posting restriction might only be enforced for restrictions originating from approvals.
+
+## NAV Versions
+
+This pattern has been introduced in Dynamics NAV 2016\.
+
+
+
+[anchor0]: attention.jpg
+[anchor1]: /navpatterns/1-patterns/blocked-entity/
+[anchor2]: https://microsoft.sharepoint.com/teams/DynamicsNAV/Wiki/Nav%20Wiki%20Documents/NAV%20App%20Patterns/NAV%20App%20Patterns%20for%20Review/Data-Driven%20Blocked%20Entity.docx#_msocom_2
+
+
+[image0]: attention.jpg