/
SUBSCRIPTION OBJECT

SUBSCRIPTION OBJECT

Owned by Josep Benavent
Last updated: Feb 16, 2024 by Pedro Jose Sanchez Luling
6 min read

In the real world we need to inscribe patients in PROGRAMS to follow the protocols defined in the PROGRAM, but we can’t simply start inscribing patients by just saying that they will follow a PROGRAM for the following reasons:

  1. There may be several TEAMS of PROFESSIONALS working with the same PROGRAM, and each TEAM should manage its own list of patients.

  2. A PROGRAM may have several versions, because it is normal that after publishing a PROGRAM we find elements that could be improved, which leads to the publication of a new improved version of the PROGRAM. Nevertheless, TEAMS that have already started using a specific PROGRAM version may decide to continue working with the same version even though new ones may be available.

This is why the SUBSCRIPTION object is necessary. A SUBSCRIPTION is an object that relates a specific version of a PROGRAM OBJECT with a TEAM OBJECT.

When we enroll a patient in a PROGRAM, in fact we are enrolling him in a SUBSCRIPTION, because we must indicate which is the TEAM that will manage the evolution of the patient. The SUBSCRIPTION also has an authorization mechanism that allows to define which PROFESSIONALS and/or TEAMS are members of the SUBSCRIPTION and with which roles.

A PROFESSIONAL member of a SUBSCRIPTION cannot manage the patients of another SUBSCRIPTION (unless he is also member of the other SUBSCRIPTION)

SUBSCRIPTIONS and PROGRAM VERSIONS

As mentioned before, a PROGRAM may have several versions, but we don’t want any change to interfere in the normal operation of the patients. To avoid problems derived from the implementation of new versions of a PROGRAM, the platform works as follows:

  • When a SUBSCRIPTION is created, it is assigned a specific PROGRAM version, which will not change even if new versions of the PROGRAM are published.

  • When a new patient is enrolled (using certain SUBSCRIPTION), then an ADMISSION OBJECT is created and assigned with the PROGRAM and version of the related SUBSCRIPTION.

  • It is possible to update a SUBSCRIPTION to use a newer version of a PROGRAM using the API function subscription_update() , but this change will not affect the existing ADMISSION that were created with a different version. The change will only affect new enrollments, which will then use the new PROGRAM version.

  • Any existing ADMISSION will always use the PROGRAM and version that was assigned at the moment of its creation. This means that even if the SUBSCRIPTION is modified to use a new version, the existing ADMISSIONS will not be affected by this change. The only way to modify the version assigned to an ADMISSION is by explicitly requesting it (using the API function admission_update ())

DRAFT PROGRAM Versions

Generally, a SUBSCRIPTION can only be assigned to a published version of a PROGRAM. This means that it is not possible to create a SUBSCRIPTION for “DRAFT” version.

But during the development of a PROGRAM it may be interesting to have the ability of testing it without the need of publishing it. Note that once a PROGRAM version is published, it can’t be modified anymore.

Since API version 2.7.32 it is possible to create a SUBSCRIPTION for a DRAFT version of a PROGRAM with some limitations:

  • Only a professional with role PROGRAM EDITOR in the TEAM owner of the OWNER can create a SUBSCRIPTION using the DRAFT version of a PROGRAM

  • When a DRAFT version is finally published, the associated SUBSCRIPTIONS will be automatically deleted

Relation between a SUBSCRIPTION and other objects

 

SUBSCRIPTION PROPERTIES

PROPERTY

TYPE

DESCRIPTION

COMMENTS

PROPERTY

TYPE

DESCRIPTION

COMMENTS

REF

String

Reference of the SUBSCRIPTION. Is the unique identifier of the SUBSCRIPTION



PROGRAM

PROGRAM OBJECT

This fields combined define the specific PROGRAM VERSION OBJECT used by this SUBSCRIPTION

A SUBSCRIPTION can only be bound to a particular version of a PROGRAM, but it can be upgraded to a different version of the same PROGRAM at any time.

VERSION

String

CREATION_DATE

Date

Date when the SUBSCRIPTION was created



MODIFICATION_DATE

Date

Date of the last modification of the SUBSCRIPTION (e.g. when it is upgraded to a new PROGRAM VERSION)



LOCKED

Boolean

When a SUBSCRIPTION is locked, the active patients can still continue working with the PROGRAM, but it will not be allowed to enroll new patients.

 

ACTIVE

Boolean

Similar to “LOCKED”, but it is not possible to mark a SUBSCRIPTION as “inactive” if it contains non-finished ADMISSIONS (ADMISSIONS that are not discharged or rejected).

So, when a SUBSCRIPTION is not active, it is not possible to enroll new patients, but it also means that there are no active patients.



DURATION

Int

Defines if the ADMISSIONS related with this SUBSCRIPTION have a maximum duration. The ADMISSIONS in this PROGRAM will be automatically discharged after the configured duration has passed counting from the date in which the ADMISSION entered the “ENROLL” stage

If this setting is not configured (null or empty), it will inherited from the PROGRAM OBJECT configuration

DURATION_UNITS

String

When a DURATION is defined, this setting it indicates the units for the duration.

Admitted values are DAYS, WEEKS, MONTHS, YEARS

If this setting is not configured (null or empty), it will inherited from the PROGRAM OBJECT configuration

EVENTS_DISABLED

Boolean

Enables or disables the creation of EVENTS in ADMISSIONs of a SUBSCRIPTION.

If this setting is not configured (null or empty), it will inherited from the PROGRAM OBJECT configuration

PREDEFINED_EVENTS

Boolean

Enables or disables default events in the program. The custom EVENTS defined in the program template will still be available.

If this setting is not configured (null or empty), it will inherited from the PROGRAM OBJECT configuration

MANUAL_ADMISSIONS_DISABLED

Boolean

Enables or disables the ability to create new ADMISSIONS in a SUBSCRIPTION manually from a client application. The API does not use this setting to prevent or allow the creation of new ADMISSIONS, since they can still be created using the API functions like admission_create ().

The goal of this setting is to inform the client applications that they should not allow a professional to create new ADMISSIONS manually.

If this setting is not configured (null or empty), it will inherited from the PROGRAM OBJECT configuration.

The API cannot control whether a patient has been created explicitly for enrolling him in the SUBSCRIPTION or whether it already existed.

CASE_ENROLL_MODE

String

Can be:

  • “ANY": The CASES enrolled in the SUBSCRIPTION can be new CASES (that should be created created before inserting a new ADMISSION) or existing CASES. The client application should allow to search for existing CASES  unless the user forces to create a new CASE. This is the default value when the PROGRAM is not a clinical trial (clinical trials by default expect to insert anonymous CASES)

  • "NEW": The CASES enrolled in the SUBSCRIPTION are always expected to be new CASES that must be created created before inserting a new ADMISSION. This is the default value when the PROGRAM is a clinical trial (clinical trials by default expect to insert anonymous CASES)

The API cannot control whether a patient has been created explicitly for enrolling him in the SUBSCRIPTION or whether it already existed.

This property is passed to the API clients (via the subscription_get () function), who should take care of this setting to not allow the creation of a new patient for enrolling him in this SUBSCRIPTION.

ONLY_EXISTING_PATIENTS

Boolean

If true, only patients that already exist in the platform can be enrolled in this SUBSCRIPTION (it is not possible to create a new patient that didn't exist before)

When this value is true, the API function case_insert() will not allow to insert new patients in this SUBSCRIPTION.

This setting is normally used when the API is connected to an external HIS and the patients are imported from it. Setting this property to ‘true’ is a way of assuring that only the patients imported from the external HIS will be eligible to enroll them in this SUBSCRIPTION

INHERIT_OWNER_TEAMS

Boolean

Indicates whether the TEAM members of the OWNER of the SUBSCRIPTION should also be considered members of the SUBSCRIPTION (with the same ROLES).

(By default this value is ‘false’ when a new SUBSCRIPTION is created)

 

INHERIT_OWNER_USERS

Boolean

Indicates whether the PROFESSIONAL members of the OWNER of the SUBSCRIPTION should also be considered members of the SUBSCRIPTION (with the same ROLES)

(By default this value is ‘true’ when a new SUBSCRIPTION is created)

 

SUBSCRIPTION MEMBERS

[SUBSCRIPTION_MEMBER]

List of TEAM OBJECT and PROFESSIONAL OBJECT added manually as members of the SUBSCRIPTION with certain permissions

 

ADMISSIONS

[ADMISSION OBJECT]

Contains the details of all ADMISSION OBJECT in the SUBSCRIPTION

 

Related functions

WS

DESCRIPTION

WS

DESCRIPTION

subscription_member_list ()

Retrieves a list of members (teams or users) that have access to the subscription defined by the session's active team and the program in the input parameter.

subscription_member_detach ()

Removes member from subscription to program.

subscription_member_role_list ()

Obtains a list of possible roles ( to add a user/team in a subscription with roles).

subscription_member_set ()

Links a user/team to a subscription with the selected roles.

subscription_get ()

Returns list of program subscriptions with STATUS = PUBLISHED

subscription_set ()

Updates settings for subscription

subscription_delete ()

remove subscription with ref = $subscription, of $team in $program



Related content