Creating Purge Rules (Study & HL7)

Purge rules are the tool by which studies and HL7 can be automatically deleted based on chosen conditions.

Rules can be added, edited, and removed either through the User Interface or the web API. This guide provides the steps for both approaches. 

Though the UI is quicker to use for creating basic rules, the API offers further configuration options for more granular control.  HL7 cannot be targeted by UI-made rules.

Remember, purge rules will  permanently delete information from the Cimar cloud. Before creating/running a rule make sure you are aware of what will be effected. If you are unsure please contact your Cimar representative or email support@cimar.co.uk.

This guide is split into the following sections:

  1. Purge Rules via the User Interface
  2. Purge Rules via the API purge/add (creating a new rule)
  3. Purge Rules via the API purge/set (editing an existing rule)

Required Permissions

To be able to work with Purge Rules, the following permissions must be enabled in a role applied to the user for  all the namespaces targeted by the rule. If you are unable to access role permissions please contact your local administrator.

Purge rules run nightly automatically. However, if you want to force execution users will also require:

To enable the above permissions, navigate via the UI:

Administration > Roles > Edit > select relevant role > Tick permissions & Save

1. Purge Rules via the User Interface

Through the UI, only studies can be targeted. See API section to target HL7.

What you  can do:

  • Delete studies or delete imaging from studies
  • Specify date, namespace, and modality conditions

To navigate to the Purge Rules interface:

  • Sign-in to Cimar
  • Click ‘Administration’
  • Select ‘Purge Rules’ from the ‘more’ dropdown menu.

Click ‘New Purge Rule’.

  • Name the rule
  • Decide how many days can elapse before a study is purged.
  • Rules can be set to run after last update, Cimar creation date, or exam date.

Creating a new rule…

Click Save and your rule will run nightly or can be run manually using the "Run" button. A dry run will test the process without actually deleting any information.

2. Purge Rules via the API purge/add

Retrieve your account_uuid.

While it is easier to add/edit a “Purge Rule” via the “User Interface”. A number of settings can only be accessed by the API. If you wish to purge Hl7 you must make a purge/add call to create a new rule. For all other API only options you can simply modify an existing rule with purge/set.

Before you navigate to the API, copy your “account_uuid” as you will need it for the next step.

Click the date & time stamp at the bottom of any Cimar page and copy the "Account uuid" from the dropdown menu.

Log into the API

Making a purge/add call

You will only need purge/add if are going to purge “Hl7” files, for all other API only changes refer to the next section “Purge Rules via the API purge/set”

A purge/add call has 5 mandatory parameters, and 6 (API only) that are optional. For this guide we will avoid any parameter you can change via the “user interface” as that is the simplest way.

Mandatory parameters

  • sid - Session id will auto generate when you open the tester.
  • name - What you wish to call your Purging Rule.
    • Value: New Purge Rule
  • account_id - The uuid of the account the rule is being created for.
    • Value: uuid of your account as retrieved above
  • days_old - how many days can elapse before a study is purged.
    • Value: 1, 2, 3, … - any number
  • days_old_how - Which date the rule counts from e.g., Updated, Created, Study date.
    • Value: U, C, S
  1. Into the URL field type purge/add. Leave Basic auth username/password blank and continue onto the “Parameters”.

The parameter is what will be changed, the value is what it will be changed to. These fields require specific input as outlined above e.g., Parameter:  days_old_how needs a value of U, or C, or S.

  1. Into the parameter fields input the 5 mandatory input’s, then input your requirements into the value field.

The following parameters are only accessable via the API but are all optional. If you are making a purge/add you will be updating object, the rest are here for reference.

API only optional parameters and acceptable Values

  • object - The object type to be purged. By default this is a “Study”, can be set to “Hl7”.
    • Value: Hl7
  • archive - Will archive studies rather than deleting them.
    • Value: 1 (on), 0 (off)
  • max_deletes - Can be used to apply a limit to the amount of studies deleted per run.
    • Value: 1, 2, 3, … - any number
  • study_status_tags - Allows you to use Study Stage tags as a filter e.g., Complete (please confirm this is accurate, I have tested in my Org and looks to be the case)
    • Value: Completed, Reported - a comma separated list of tags to filter by
  • skinny - Removes all DICOM images from the study but leaves attachments.
    • Value: 1 (on), 0 (off)
  • shared_from_phr - Will also delete the copy of any study shared from the PHR namespace.
    • Value: 1 (on), 0 (off)

  1. Input the next parameter as “object” with a value of “Hl7”.
  2. Continue to apply any of the other API only optional setting you require.
  3. Suspend this rule so it will not automatically run with the following parameter.
    • Parameter: suspended
    • Value: 1

  1. Scroll to the bottom of the page and click the “Submit” button.

At the top of page a confirmation message will appear with the “uuid” of the rule you have created and a “status” of “OK”.

Return to your Cimar account and check the rule

  1. Return to the Purging Rules section of your Cimar account as per part one of this guide and you will see your new rule. Currently it is suspended and will not run.
  2. To activate the rule click the “Edit” button.

  1. Update any setting you require then un-check the “Suspend this rule” box and “save”

Your rule is now active and will automatically run each night.

3. Purge Rules via the API purge/set

Log into the API

  • To access the api proceed to cloud.cimar.co.uk/api/v3 and log in with your Cimar credentials.
  • Click the “API Tester” link.

  1. Make a purge/list call with the following parameters
  • sid - Session id will auto generate when you open the tester.
  • account_id - The uuid of the account the rule is being created for. (Refer to previous section to find account_uuid)
    • Value: uuid of your account as retrieved above

This will return a list of all “Purge rules” associated with the account. This list will be randomly populated every time the call is made so you will have to look for the rule you wish to alter. It can be helpful to use “ctrl + f” (PC) or “cmd + f” (Mac) to search for the name of the rule you created.

  1. Locate your rule by its name then copy the “uuid” value. Make sure you choose the “uuid” as the value will look similar to the “account_id” & “namespace”.
  2. Refresh the page to clear all input fields ready for the next step.

Make a purge/set call

  1. Perform a purge/set with the following mandatory parameters.
  • sid - The session id will auto populate (do not change)
  • uuid - The uuid of the rule you wish to alter
    • value: the uuid of the rule as copied above
  1. Apply any of the optional parameters you require.
  • archive - Will archive studies rather than deleting them.
    • Value: 1 (on), 0 (off)
  • max_deletes - Can be used to apply a limit to the amount of studies deleted per run.
    • Value: 1, 2, 3, … - any number
  • study_status_tags - Allows you to use Study Stage tags as a filter e.g., Completed
    • Value: Completed, Reported - a comma separated list of tags to filter by
  • skinny - Removes all DICOM images from the study but leaves attachments.
    • Value: 1 (on), 0 (off)
  • shared_from_phr - Will also delete the copy of any study shared from the PHR namespace.
    • Value: 1 (on), 0 (off)

  1. Scroll to the bottom of the page and click the “Submit” button.

At the top of page a confirmation message will appear with a “status” of “OK”.

Still need help? Contact Us Contact Us