Functions.md

LSAPIs Functions

This is a detailed outline of all the public functions created in the LSAPIs.py file. There are a few other functions used internally in the module but not listed here.

Note that the functions here are listed identified with LegalServer's convention that a GET API call that does not specify a uuid is a Search API. All the functions start with that verb/convention.

get_legalserver_report_data

This is a function that will get a LegalServer report and return the data in a python dictionary.

This uses the LegalServer Reports API to get any report type data back from LegalServer and return it as a python dictionary. LegalServer Report APIs can return data in either JSON or XML format and this will parse either into a python dictionary. Note that LegalServer's JSON content is not perfect. True/False are rendered as t and f instead of JSON booleans. Also integers are returned as strings. It is also worth noting that the Reports API typically defaults to include hidden columns. This function defaults to exclude them unless otherwise specified.

Parameters

• legalserver_site - required
• display_hidden_columns - optional boolean to allow for hidden columns (in the LegalServer Report) to be excluded or included from the results. This defaults to False.
• report number - required integer for the specific report
• report_params - optional dictionary of additional filters

get_matter_details

This is a keyword defined function that retrieves all the details available on a case using the LegalServer Get Matter Details API. This returns the json dictionary of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• custom_fields - optional python list of string values
• custom_fields_charges - optional python list of string values
• custom_fields_litigations - optional python list of string values
• custom_fields_services - optional python list of string values
• sort - optional string to sort the results

search_organization_data

This is a keyword defined function that searches for organizations based on a set of criteria passed in the organization_search_params. This uses the Legalserver Search Organizations API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• organization_search_params - optional python dictionary of any search parameters
• custom_fields - optional python list of string values
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

get_organization_details

This is a keyword defined function that gets details back on a specific organization record. This allows for the identification of the custom fields as well. This uses the Get Organizations API endpoint. This returns the json dictionary of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_organization_uuid - required
• custom_fields - optional python list of string values

search_user_data

This is a keyword defined function that searches for users based on a set of criteria passed in the user_search_params. This uses the Legalserver Search Users API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• user_search_params - optional python dictionary of any search parameters
• custom_fields - optional python list of string values
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

get_user_details

This is a keyword defined function that gets details back on a specific user record. This allows for the identification of the custom fields as well. This uses the Get User API endpoint. This returns the json dictionary of the data returned by the API.

This makes a followup API call to get the organization affiliation data for the same user before returning all of that data in the response. This uses the Search User Organization Affiliation API endpoint.

Parameters

• legalserver_site - required
• legalserver_user_uuid - required
• custom_fields - optional python list of string values

search_contact_data

This is a keyword defined function that searches for contacts based on a set of criteria passed in the contact_search_params. This uses the Legalserver Search Contacts API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• contact_search_params - optional python dictionary of any search parameters
• custom_fields - optional python list of string values
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

get_contact_details

This is a keyword defined function that gets details back on a specific contact record. This allows for the identification of the custom fields as well. This uses the Get Contact API endpoint. This returns the json dictionary of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_contact_uuid - required
• custom_fields - optional python list of string values

search_matter_additional_name_data

This is a keyword defined function that searches a specific matter for additional names of the client. This uses the Search Matter Additional Names API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• matter_additional_names_search_params - Optional dictionary of search parameters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_matter_adverse_parties

This is a keyword defined function that searches a specific matter for adverse Parties. This uses the Search Matter Adverse Parties API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• matter_adverse_parties_search_params - Optional dictionary of search parameters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_matter_assignment_data

This is a keyword defined function that searches a specific matter for assignments. This uses the Search Matter Assignments API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required string for the LegalServer Matter's UUID
• matter_assignment_search_params - optional python dictionary of filters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_matter_charges_data

This is a keyword defined function that searches a specific matter for charges. This uses the Search Matter Charges API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• charges_search_params - Optional dictionary of search parameters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_matter_contacts_data

This is a keyword defined function that searches a specific matter for case contacts. This uses the Search Matter Contacts API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• matter_contact_search_params - Optional dictionary of search parameters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_matter_litigation_data

This is a keyword defined function that searches a specific matter for litigations. This uses the Search Matter Litigations API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• litigation_search_params - Optional dictionary of search parameters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_matter_non_adverse_parties

This is a keyword defined function that searches a specific matter for Non-Adverse Parties. This uses the Search Matter Non-Adverse Parties API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• matter_non_adverse_parties_search_params - Optional dictionary of search parameters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_matter_notes_data

This is a keyword defined function that gets back all of the notes on a case. The notes can be filtered in the API call based on the note_type. This uses the Search Matter Notes API endpoint. They are returned as a list of notes.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• note_type - Optional string to filter on Note Type
• search_note_params - Optional dictionary of search parameters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_matter_services_data

This is a keyword defined function that searches a specific matter for Services. This uses the Search Matter Services API endpoint. This returns the json list of the data returned by the API.

Parameters

• legalserver_site - required
• legalserver_matter_uuid - required
• services_search_params - Optional dictionary of search parameters
• sort - optional string to sort the results
• page_limit - optional limit to the number of pages returned

search_user_organization_affiliation

This is a keyword defined function that gets back all of the organization affiliation records on a user. This uses the Search User Organization Affiliation API endpoint. They are returned as a list of Organization Affiliations.

Parameters

• legalserver_site - required string
• legalserver_user_uuid - required string

populate_additional_names

This is a keyword defined function that takes a DAList of IndividualNames and populates it with the contact details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_matter_additional_names function. Since the standard response from the get_matter_details does not include this data, it will always make that call.

Parameters

• additional_name_list - required DAList of Individuals for the contacts
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided

populate_adverse_parties

This is a keyword defined function that takes a DAList of Persons and populates it with the assignment details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_matter_adverse_parties function.

Parameters

• adverse_party_list - DAList of Persons. Note that if it is an Individual Adverse Party, the name attribute will be set to an IndividualName.
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided

populate_assignments

This is a keyword defined function that takes a DAList of DAObjects and populates it with the assignment details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_assignment_data function.

Parameters

• assignment_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided

populate_case

This is a keyword defined function that takes a DAObject and populates it with the case related details related to a case. It requires the general legalserver_data from the get_matter_details response.

Parameters

• case - DAObject
• legalserver_data - the full case data returned from the Get Matter API call to LegalServer

populate_charges

This is a keyword defined function that takes a DAList of DAObjects and populates it with the charge details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_matter_charges_data function.

Parameters

• charge_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• custom_fields - Optional list of field names for custom fields to include

populate_client

This is a keyword defined function that takes a the general legalserver_data from the get_matter_details and saves the client related data to either an Individual or a Person depending on whether the client is an individual or a group.

Parameters

• client - Either an Individual or a Person object
• legalserver_data - the full case data returned from the Get Matter API call to LegalServer

populate_contacts

This is a keyword defined function that takes a DAList of Individuals and populates it with the contact details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_contact_data function.

Parameters

• contact_list - required DAList of Individuals for the contacts
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• custom_fields - Optional list of field names for custom fields to include

populate_current_user

This is a keyword defined function that takes an Individual object and populates it with the user data of the user who initiated the Docassemble Interview from LegalServer.

Parameters

• legalserver_current_user - Individual object that will be returned
• legalserver_current_user_uuid - needed to identify the user.
• legalserver_site - needed to identify the site.
• user_custom_fields - Optional list of custom fields to gather on the User record.

populate_events

This is a keyword defined function that takes a DAList of DAObjects and populates it with the event details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_event_data function.

Note that because this package is designed to connect LegalServer cases to Docassemble, it does not address the Outreaches key present in the LegalServer event response.

Parameters

• event_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• custom_fields - Optional list of field names for custom fields to include

populate_first_pro_bono_assignment

This is a keyword defined function that takes an Individual object and populates it with the user data of the earliest Pro Bono assignment on a case that has not yet ended. This needs populate_assignment() run first so that it can parse the list of assignments on the case for the expected Pro Bono assignment.

Parameters

• legalserver_first_pro_bono_assignment - Individual object that will be returned
• assignment_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• user_custom_fields - Optional list of custom fields to gather on the User record.

populate_income

This is a keyword defined function that takes a DAList of DAObjects and populates it with the income details related to a case. If the general legalserver_data from the get_matter_details response is not included, it would make an API call using the search_income_data function. Unfortunately, the Search Income API endpoint does not currently exist.

Parameters

• income_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided

populate_latest_pro_bono_assignment

This is a keyword defined function that takes an Individual object and populates it with the user data of the latest Pro Bono assignment on a case that has not yet ended. This needs populate_assignment() run first so that it can parse the list of assignments on the case for the expected Pro Bono assignment.

Parameters

• legalserver_latest_pro_bono_assignment - Individual object that will be returned
• assignment_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• user_custom_fields - Optional list of custom fields to gather on the User record.

populate_litigations

This is a keyword defined function that takes a DAList of DAObjects and populates it with the litigation details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_matter_litigation_data function.

Parameters

• litigation_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• custom_fields - Optional list of field names for custom fields to include

populate_notes

This is a keyword defined function that takes a DAList of DAObjects and populates it with the note details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_matter_notes_data function.

Parameters

• note_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided

populate_primary_assignment

This is a keyword defined function that takes an Individual object and populates it with the user data of the current primary assignment on a case. This needs populate_assignment() run first so that it can parse the list of assignments on the case for the current primary assignment.

Parameters

• primary_assignment - Individual object that will be returned
• assignment_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• user_custom_fields - Optional list of custom fields to gather on the User record.

populate_pro_bono_assignments

This is a keyword defined function that takes a DAList of Individuals and populates it with the user data of all the assigned Pro Bono assignments on a case whose assignments have not yet been ended. This needs populate_assignment() run first so that it can parse the list of assignments on the case for the current primary assignment.

Parameters

• pro_bono_assignment_list - DAList object of Individual objects that will be returned
• assignment_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• user_custom_fields - Optional list of custom fields to gather on the User record.

populate_services

This is a keyword defined function that takes a DAList of DAObjects and populates it with the service details related to a case. If the general legalserver_data from the get_matter_details response is not included, it will make an API call using the search_matter_service_data function.

Parameters

• service_list - DAList of DAObjects
• legalserver_data - Optional dictionary of the matter data from a LegalServer request
• legalserver_matter_uuid - needed if the legalserver_data is not provided
• legalserver_site - needed if the legalserver_data is not provided
• custom_fields - Optional list of field names for custom fields to include

populate_user_data

This is a keyword defined function that helps populate an Individual record with details from the Get User API response.

Parameters

• user - The Individual object to be populated and returned.
• user_data - The get_user_details() response dictionary that has the information to populate the record with.

post_file_to_legalserver_documents_webhook

This is a keyword defined function that takes three required parameters and one optional parameter. Like the other function, it requires the legalserver_site and legalserver_matter_uuid to link back to the case. It also takes the file_path of the file that was generated in Docassemble. This can be retrieved by using .path() with the file variable. If the file uploaded is a zip file, the file will be saved to the case, unzipped to the specified folder (or the root directory if one was not supplied) and a case note linked to those documents created. If the file is not a zip file, it will just be saved to the case. The folder can be specified with the subfolder optional parameter. This uses the Post Documents to LegalServer as a Zip endpoint.

Parameters

• legalserver_site - required string for the LegalServer Site Abbreviation
• legalserver_matter_uuid - required string for the LegalServer Matter UUID
• file_path - required string for the path to the file to be sent.
• subfolder - optional string to identify a subfolder to store the file in when uploaded to LegalServer
• save_to_sharepoint - optional boolean to save the file to the case's SharePoint case folder instead of the LegalServer document storage.

country_code_from_name

This uses the PyCountry module's fuzzy search to convert the name of the country to the alpha_2 abbreviation. Docassemble uses the abbreviation for location recognition, but LegalServer stores the name of the country, so this allows access to both. If multiple countries are identified, the response is "Unknown" and the error is logged.

There is a built in override that forces "United States" to return "US". Otherwise, it will return "US", "UM", and "VI".

Parameters

• country_name_string - required string

language_code_from_name

This uses the PyCountry module to convert the name of the language to the alpha_2 abbreviation. Docassemble uses the abbreviation for language recognition, but LegalServer stores the name of the language, so this allows access to both.

Parameters

• language_name - required string

is_zip_file

This is a small helper function to identify whether the file_path presented is a zip file. This makes a difference when uploading the file to LegalServer.

Parameters

• file_path - required string

check_legalserver_token

Returns True if two things are true:

1. An API token for the given site is present in Docassemble's Config file.
2. The Expiration date for the API token has not passed.

Parameters

• legalserver_site - required string for the LegalServer Site Abbreviation

count_of_pro_bono_assignments

Simple function that checks how many pro bono assignments there are.

Parameters

• pro_bono_assignment_list - required DAList of assignments

list_templates

This is a small helper function that allows you to get a list of all the templates stored in the /data/templates folder of a given package. If no package is specified, it will check against the current package. A list of strings is returned.

Parameters

• package - optional string name of a Docassemble package.

Standard Keys

There are functions also designed to just return the list of standard keys returned in the LegalServer API calls. This makes it easier to identify when there are custom fields present in the API response. These exist for the following LegalServer response objects:

• Additional Names
• Adverse Parties
• Assignments
• Charges
• Client Addresses
• Contacts
• Documents
• Events
• Incomes
• Litigations
• Matters
• Non-Adverse Parties
• Organizations
• Services
• Tasks
• Users