Add more examples to e-filing integration

docs/efiling/efiling_through_docassemble.md

@@ -83,9 +83,65 @@ We'll first need to find the right "codes" for our interview. Tyler's E-filing s
 parts of the filing process, include the over-arching category of the case, the more specific case type, and even things like whether or not
 the filed document should be confidential or not.
 
-To find the right codes, navigate through the URLs provided by visiting [https://efile-test.suffolklitlab.org/jurisdictions/illinois/codes](https://efile-test.suffolklitlab.org/jurisdictions/illinois/codes).
-Firefox will display clickable links that you can use to browse the different codes.
+You will usually need to lookup the `case category` and the `case type`. The docassemble integration allows some fuzzy matching based
+on the name of the case type or category, because codes can change without warning. But in some cases, you will want to specify the exact code. Therefore,
+you will want to note and enter both the name and the associated code for both case category and case type.
 
+https://efile-test.suffolklitlab.org/ has a fairly complete interface to help you locate codes. But:
+
+* You might need to write down a code you get at one step to effectively use it as a required parameter or in the endpoint URL in a follow-up search.
+* One common example is the court's name. The court code is often required to be part of the endpoint's path. Court codes are often
+the same as the court's name, but may have a slight variation. You can look up the court code.
+* Some of the endpoints require that you add a URL parameter. URL parameters follow standard GET rules, with the first parameter needing a `?` and each following parameter separated by an `&`. The value for each parameter follows a `=`. E.g., ?paramater1=value&parameter2=value
+
+#### Find the jurisdiction and start browsing services and codes
+1. Locate the jurisdiction you want by visiting [https://efile-test.suffolklitlab.org/jurisdictions/](https://efile-test.suffolklitlab.org/jurisdictions/). You can click on the URL next to the jurisdiction name to visit the page for that jurisdiction's courts.
+1. Find the "GetCodesService" link to browse all available codes. For example: [https://efile-test.suffolklitlab.org/jurisdictions/massachusetts/codes/](https://efile-test.suffolklitlab.org/jurisdictions/massachusetts/codes).
+
+#### Find the code for a court
+1. Find the code for the court that you want to file in by visiting the "GetCourts" link. It may help to add the parameter ?with_names=true. For example: [https://efile-test.suffolklitlab.org/jurisdictions/massachusetts/codes/courts?with_names=true](https://efile-test.suffolklitlab.org/jurisdictions/massachusetts/codes/courts?with_names=true). Note: the available paramaters are documented on the previous page, with the link to each available service.
+1. Note the appropriate court code. For example, "appeals:acsj" is the code associated with "Appeals Court - Single Justice (J Docket)".
+
+#### Find the case category name and code
+1. Go back to the "GetCodesService" link (https://efile-test.suffolklitlab.org/jurisdictions/massachusetts/codes/) and click the example link for 
+the getCategories service. You will need to edit the URL to place the proper court code in the URL. For example: https://efile-test.suffolklitlab.org/jurisdictions/massachusetts/codes/courts/appeals:acsj/categories, where `appeals:acsj` is the court code.
+1. Note the case category's name and code. For example: Case category "Appeals Court Single Justice - Civil" has the associated code 8151.
+
+#### Find the code for the case type
+1. To get the code for a case type, we need to look at the case types available for a specific category associated with a specific court. 
+1. Visit the getCaseTypes service. Edit the example URL to **specify both the court code and a category ID.** For example: https://efile-test.suffolklitlab.org/jurisdictions/massachusetts/codes/courts/appeals:acsj/case_types?category_id=8151
+1. Look through the list of codes and pick the appropriate code. For example, for a "MAC Rule 6.0 – Motion to stay" the code is 101447.
+
+Note that some jurisdictions may use the same case type code for all cases of the same type, across all courts. But at least one jurisdiction, Illinois, uses 
+different codes in different courts. The most recent version of the `efiling_integration.yml` provided by docassemble-EFSPIntegration allows you to reference 
+the filing code by name to resolve this problem, but some fuzzy matching may be necessary because even the name for the case type can have variations in 
+Illinois.
+
+#### Find the code for the filing type
+
+In addition to a case type that describes the whole "envelope", individual documents inside the case type have their own codes.
+
+1. Use the getFilingTypes endpoint to get a list of available filing types and their associated codes. For example: https://efile-test.suffolklitlab.org/jurisdictions/massachusetts/codes/courts/appeals:acsj/filing_types.
+1. You can search in the page for the matching filing type. For example, for "Rule 6.0 Motion to Stay" the filing type is 101450.
+
+Assuming that your Docassemble interview allows filing exactly one case type and category, the efiling_integration.yml file will expect to find the codes defined this way:
+
+```yaml
+code: |
+  efile_case_category_filters = ['Appeals Court Single Justice - Civil', 'Civil']
+  efile_case_category_default = '8151'
+  efile_case_category_exclude = None
+  efile_case_type_filters = ['Rule 6.0 Motion to Stay']
+  efile_case_type_default = '101447'
+  efile_case_type_exclude = None
+```
+
+The filing type is defined at the bundle level (note you can have as many bundles as you choose in a given interview).
+
+```yaml
+
+
+#### Complete example -- Illinois single court adoption codes
 For example, say we want to write an Adoption interview. The codes in Illinois are split by courts, so to see the case categories available to
 one particular court, say Adams, we can go to
 [https://efile-test.suffolklitlab.org/jurisdictions/illinois/codes/courts/adams/categories](https://efile-test.suffolklitlab.org/jurisdictions/illinois/codes/courts/adams/categories), and scroll through the responses until we find the "Adoption" entry,
@@ -94,8 +150,6 @@ code 7306. We would then see the case types for Adoption cases in adams at
 
 The endpoints should say when they need parameters, like we provided with `category_id=7306&timing=Initial` above.
 
-We are currently working on a better interface for finding and handling these codes at runtime based on our experiences in Illinois and Massachusetts. Stay tuned.
-
 For this guide, we'll stick with a single court, to make things simple to understand. We'll use the following codes:
 
 variable name | purpose | example value | example meaning

sidebars.js

@@ -159,6 +159,7 @@ module.exports = {
                 'efiling/overview',
                 'efiling/efiling_through_docassemble',
                 'efiling/efiling_case_search',
+                'efiling/efiling_codes',
                 'efiling/monitoring',
             ]
         },