What are the pros and cons of using external xml files for CiviCase configuration?

Question

In CiviCase since 4.5-ish there's been an admin screen for configuring case types. Before that it was done using external xml files, and they will still work. What are the pros and cons of each method?

Answer 1

I decided not to submit this as an official documentation update because here it can be a bit looser with the language and this also allows tweaking it a bit first.

CONS:

• If you hate xml you might not want to use xml files.

  • ASIDE: If you're wondering why it wasn't done in some other format, note that at the time xml was widely used and json had only been proposed as an RFC spec and support for json wasn't included in stock php. XML was already used in Civi for the schema templates. Using .ini files is awkward with nested/multivalued settings. Using .php files wouldn't have been portable to non-civi systems which was a grander vision at the time (yes, really).

• Upgrades that require changes to the definition can't be done by the standard civi upgrade if the webserver doesn't have write access to the files.
• None of the "pro" reasons below matter to you and you prefer a GUI.
• If you really like making typos and/or not testing changes before putting on a live site you can bork your site more easily.
• Forgetting to transfer them when you move or duplicate a site. Although if you store them in the custom templates folder which you manage with git/svn then unless those are the only customizations in there you'd be less likely to forget.

On the PRO side:

• There's all the reasons people use external config files for other software, including:
  • Versioning via git or otherwise, and regular diff'ing tools work.
  • Mass updates easily done with command line tools, e.g. if you want to add a new activity type to all your case types and you have 10 case types it's 50 clicks plus some scrolling in the UI. That's not terrible, and you don't usually do it that often, but it's easier to do with text files. Or for example if you want to add a case type that's similar to an existing one, then copying the file and making a few changes is easier.
  • (Partial) Portability between installs. Not just copying a site, but between two otherwise different sites that might want to share some of the same configuration. The original plan was to be able to take your file, plop it into another civi site, and have it automatically work. That was never fully implemented, but it does work with some extra steps. (See a separate discussion about being able to export/import all CiviCRM configuration settings, which would be a more general solution.)
  • More granular permissions on configuration, e.g. prevent junior admin users from making accidentally bad configuration changes.
• Custom settings are (relatively) easy to add and use. For example, in the CaseRoles section you could do like this:

<CaseRoles>
  <RelationshipType>
    <name>something</name>
    <mythings>
      <mything>thing1</mything>
      <mything>thing2</mything>
    </mythings>
    ... etc ...

In some sections it's even automatically picked up by the api, e.g. when you do an api call to CaseType get, the above comes through as:

[caseRoles] => Array
  (
    [0] => Array
      (
        [name] => something
        [mythings] => Array
          (
            [mything] => Array
              (
                [0] => thing1
                [1] => thing2
              )
          )
     )

Even if it's in a section where the api doesn't pick it up, since you're doing custom stuff anyway you can load and parse the xml file. (You can still do custom data using database storage, you just need to store the custom data in a different table and reference it separately.)

Why is there no documentation?

I don't know why the old wiki docs weren't transferred over, but it is still available and mostly still true on the old wiki at e.g. https://wiki.civicrm.org/confluence/display/CRMDOC43/CiviCase+Configuration#CiviCaseConfiguration-Step-by-step.

The part that is no longer correct is at https://wiki.civicrm.org/confluence/display/CRMDOC43/CiviCase+Configuration#CiviCaseConfiguration-CaseTypes, since case type identifiers are no longer option values and are now in the civicrm_case_type table, and unfortunately that link also demonstrates some of the confusion regarding name vs label in the past. Ignore that part. Pleeeeeeeese ignore that part.

Converting xml files to database storage

If you have an existing site already using xml files, this is as simple as visiting administer - civicase - case types and clicking edit on your case type and then clicking save. The files will get converted and will now be ignored.

You should probably then move the file out of the way to avoid confusion over which definition is in effect.

Preventing converting xml files to database storage

If somebody does the above and didn't mean to, this could be confusing if somebody else later edits the file thinking it still controls the definition. If you want to prevent converting, then in the xml file add <forkable>0</forkable> near the top of the file, e.g.

<CaseType>
  <name>housing_support</name>`
  <forkable>0</forkable>
  ...

Converting database storage to xml files

1. In your database in the civicrm_case_type table in the definition field there will be some xml.
2. Copy and paste or otherwise put that data into a file with the same name as the name field in that row, e.g. housing_support.xml. The file should be in your custom templates directory as described at the above wiki documentation link.
3. Then put NULL into the definition field in the database.
4. From then on it will use the configuration in the file.
5. Also see the section above about preventing someone accidentally converting it back to database if you want to prevent that.

Using xml files from scratch

Ironically, the way history has unfolded probably the easiest way to do this now is to use the UI to create the type and then do the same as converting database to files above.