docs: update docs for custom scopes

v1.7.0/setup/3.-installation/3.2-set-up-your-own-country-configuration/3.2.4-set-up-employees-for-testing-or-production/4.2.3.1-configure-roles.md

@@ -0,0 +1,34 @@
+# 4.2.3.1 Configure roles
+
+OpenCRVS has a pre-configured set of user roles with various scopes, but you can change them to have any combination of scopes that you need. You can also create completely new roles. All of these roles are defined in the `roles.ts` file in the `src/data-seeding/roles` directory of the opencrvs-countryconfig repository. This particular file has a `roles` array that contains all the roles that will be available in your OpenCRVS instance. Now let's take a look at how we can define a new role:
+
+```typescript
+{
+    id: 'DATA_ENTRY_CLERK',
+    label: {
+      defaultMessage: 'Data entry clerk',
+      description: 'Name for user role data entry clerk',
+      id: 'userRole.dataEntryClerk'
+    },
+    scopes: [
+      SCOPES.RECORD_DECLARE_BIRTH,
+      SCOPES.RECORD_DECLARE_DEATH,
+      SCOPES.RECORD_DECLARE_MARRIAGE,
+      SCOPES.RECORD_SUBMIT_INCOMPLETE,
+      SCOPES.RECORD_SUBMIT_FOR_REVIEW,
+      SCOPES.SEARCH_BIRTH,
+      SCOPES.SEARCH_DEATH,
+      SCOPES.SEARCH_MARRIAGE
+    ]
+}
+```
+
+* The `id` field is the unique identifier for the role.
+* The `label` field can be used to configure how the role would show up in the application. A corresponding entry in the `client.csv` file for the id `userRole.dataEntryClerk` would need to be created to provide translations for the label.
+* The `scopes` field is an array of scopes that the role has access to. The `SCOPES` constant has all the available scopes that can be used in the system. More details on each scope is added in the next section.
+
+Adding this entry to the `roles` array in the `roles.ts` file will make the role available in the OpenCRVS instance.
+
+{% hint style="danger" %}
+If you are upgrading from a previous version of OpenCRVS, **Do not modify the existing roles** in the `roles.ts` file to make the upgrade backward compatible. Instead, add new roles if needed.
+{% endhint %}