org.openmrs.api
Interface FormService

All Superinterfaces:

OpenmrsService

All Known Implementing Classes:

FormServiceImpl

@Transactional
public interface FormService
extends OpenmrsService

This service contains methods relating to Form, FormField, and Field. Methods relating to FieldType are in AdministrationService

Method Summary

void	createField(Field field) Deprecated. use saveField(Field)
Form	createForm(Form form) Deprecated. use saveForm(Form)
void	createFormField(FormField formField) Deprecated. use saveFormField(FormField)
void	deleteField(Field field) Deprecated. use purgeField(Field)
void	deleteForm(Form form) Deprecated. use purgeForm(Form)
void	deleteFormField(FormField formField) Deprecated. use purgeFormField(FormField)
Form	duplicateForm(Form form) Duplicate this form and form_fields associated with this form
java.util.List<Field>	findFields(Concept concept) Deprecated. use getFieldsByConcept(Concept)
java.util.List<Field>	findFields(java.lang.String searchPhrase) Deprecated. use getFields(String)
java.util.List<Form>	findForms(java.lang.String text, boolean includeUnpublished, boolean includeRetired) Deprecated. use getForms(String, Boolean, Collection, Boolean, Collection, Collection)
java.util.List<Field>	getAllFields() Fetches all Fields in the database, including retired ones
java.util.List<Field>	getAllFields(boolean includeRetired) Fetches all Fields in the database, possibly including retired ones
java.util.List<FieldType>	getAllFieldTypes() Get all field types in the database including the retired ones
java.util.List<FieldType>	getAllFieldTypes(boolean includeRetired) Get all field types in the database with or without retired ones
java.util.List<FormField>	getAllFormFields() Returns all FormFields in the database
java.util.List<Form>	getAllForms() Gets all Forms, including retired ones.
java.util.List<Form>	getAllForms(boolean includeRetired) Gets all forms, possibly including retired ones
Field	getField(java.lang.Integer fieldId) Gets a Field by internal database id
java.util.List<Field>	getFields() Deprecated. use getAllFields()
java.util.List<Field>	getFields(java.util.Collection<Form> forms, java.util.Collection<FieldType> fieldTypes, java.util.Collection<Concept> concepts, java.util.Collection<java.lang.String> tableNames, java.util.Collection<java.lang.String> attributeNames, java.lang.Boolean selectMultiple, java.util.Collection<FieldAnswer> containsAllAnswers, java.util.Collection<FieldAnswer> containsAnyAnswer, java.lang.Boolean retired) Returns all Fields that match these (nullable) criteria
java.util.List<Field>	getFields(java.lang.String fuzzySearchPhrase) Find all Fields whose names are similar to or contain the given phrase.
java.util.List<Field>	getFieldsByConcept(Concept concept) Finds all Fields that point to the given concept, including retired ones.
FieldType	getFieldType(java.lang.Integer fieldTypeId) Get fieldType by internal identifier
java.util.List<FieldType>	getFieldTypes() Deprecated. use getAllFieldTypes()
Form	getForm(java.lang.Integer formId) Get form by internal form identifier
Form	getForm(java.lang.String name) Get form by exact name match.
Form	getForm(java.lang.String name, java.lang.String version) Get form by exact name & version match.
FormField	getFormField(Form form, Concept concept) Finds the FormField defined for this form/concept combination Calls #getFormField(Form, Concept, Collection) with an empty ignore list and with force set to false
FormField	getFormField(Form form, Concept concept, java.util.Collection<FormField> ignoreFormFields, boolean force) Finds the FormField defined for this form/concept combination while discounting any form field found in the ignoreFormFields collection This method was added when needing to relate observations to form fields during a display.
FormField	getFormField(java.lang.Integer formFieldId) Gets a FormField by internal database id
java.util.List<FormField>	getFormFields(Form form) Deprecated. use Form.getFormFields()
java.util.List<Form>	getForms() Deprecated. use getAllForms()
java.util.List<Form>	getForms(boolean publishedOnly) Deprecated. use getAllForms() or getPublishedForms()
java.util.List<Form>	getForms(boolean publishedOnly, boolean includeRetired) Deprecated. use getAllForms() or getPublishedForms() or getForms(String, Boolean, Collection, Boolean, Collection, Collection)
java.util.Set<Form>	getForms(Concept c) Deprecated. use getFormsContainingConcept(Concept)
java.util.List<Form>	getForms(java.lang.String fuzzyName, boolean onlyLatestVersion) Gets all forms with name similar to the given name.
java.util.List<Form>	getForms(java.lang.String partialNameSearch, java.lang.Boolean published, java.util.Collection<EncounterType> encounterTypes, java.lang.Boolean retired, java.util.Collection<FormField> containingAnyFormField, java.util.Collection<FormField> containingAllFormFields) Gets all forms that match all the (nullable) criteria
java.util.List<Form>	getFormsContainingConcept(Concept concept) Returns all forms that contain the given concept as a field in their schema.
java.util.List<Form>	getPublishedForms() Returns all published forms (not including retired ones)
void	purgeField(Field field) Completely removes a Field from the database.
void	purgeField(Field field, boolean cascade) Completely removes a Field from the database.
void	purgeFieldType(FieldType fieldType) Deletes the given field type from the database.
void	purgeForm(Form form) Completely remove a Form from the database.
void	purgeForm(Form form, boolean cascade) Completely remove a Form from the database.
void	purgeFormField(FormField formField) Completely removes the given FormField from the database.
Field	retireField(Field field) Retires field
void	retireForm(Form form, java.lang.String reason) Retires the Form, leaving it in the database, but removing it from data entry screens
Field	saveField(Field field) Creates or updates the given Field
FieldType	saveFieldType(FieldType fieldType) Saves the given field type to the database
Form	saveForm(Form form) Create or update the given Form in the database
FormField	saveFormField(FormField formField) Creates or updates the given FormField
Field	unretireField(Field field) Unretires field
void	unretireForm(Form form) Unretires a Form that had previous been retired.
void	updateField(Field field) Deprecated. use saveField(Field)
void	updateForm(Form form) Deprecated. use saveForm(Form)
void	updateFormField(FormField formField) Deprecated. use saveFormField(FormField)

Methods inherited from interface org.openmrs.api.OpenmrsService

onShutdown, onStartup

Method Detail

saveForm

@Authorized(value="Manage Forms")
Form saveForm(Form form)
              throws APIException

Create or update the given Form in the database

Parameters:

form - the Form to save

Returns:

the Form that was saved

Throws:

APIException

createForm

@Authorized(value="Manage Forms")
Form createForm(Form form)
                throws APIException

Deprecated. use saveForm(Form)

Throws:

APIException

getForm

@Transactional(readOnly=true)
@Authorized(value="View Forms")
Form getForm(java.lang.Integer formId)
             throws APIException

Get form by internal form identifier

Parameters:

formId - internal identifier

Returns:

requested form

Throws:

APIException

getForm

@Transactional(readOnly=true)
@Authorized(value="View Forms")
Form getForm(java.lang.String name)
             throws APIException

Get form by exact name match. If there are multiple forms with this name, then this returns the one with the highest version (sorted alphabetically)

Parameters:

name - exact name of the form to fetch

Returns:

requested form

Throws:

APIException

getForm

@Transactional(readOnly=true)
@Authorized(value="View Forms")
Form getForm(java.lang.String name,
                                           java.lang.String version)
             throws APIException

Get form by exact name & version match. If version is null, then this method behaves like getForm(String)

Parameters:

name - exact name of the form to fetch

version - exact version of the form to fetch

Returns:

requested form

Throws:

APIException

getAllForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getAllForms()
                                 throws APIException

Gets all Forms, including retired ones.

Returns:

all Forms, including retired ones

Throws:

APIException

getAllForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getAllForms(boolean includeRetired)
                                 throws APIException

Gets all forms, possibly including retired ones

Parameters:

includeRetired - whether or not to return retired forms

Returns:

all forms, possibly including retired ones

Throws:

APIException

getForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getForms(java.lang.String fuzzyName,
                                                            boolean onlyLatestVersion)

Gets all forms with name similar to the given name. (The precise fuzzy matching algorithm is not specified.)

Parameters:

fuzzyName - approximate name to match

onlyLatestVersion - whether or not to return only the latest version of each form (by name)

Returns:

forms with names similar to fuzzyName

getForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getForms(java.lang.String partialNameSearch,
                                                            java.lang.Boolean published,
                                                            java.util.Collection<EncounterType> encounterTypes,
                                                            java.lang.Boolean retired,
                                                            java.util.Collection<FormField> containingAnyFormField,
                                                            java.util.Collection<FormField> containingAllFormFields)

Gets all forms that match all the (nullable) criteria

Parameters:

partialNameSearch - partial search of name

published - whether the form is published

encounterTypes - whether the form has any of these encounter types

retired - whether the form is retired

containingAnyFormField - includes forms that contain any of the specified FormFields

containingAllFormFields - includes forms that contain all of the specified FormFields

Returns:

All forms that match the

getPublishedForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getPublishedForms()
                                       throws APIException

Returns all published forms (not including retired ones)

Returns:

all published non-retired forms

Throws:

APIException

getForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getForms(boolean publishedOnly)
                              throws APIException

Deprecated. use getAllForms() or getPublishedForms()

Get all forms. If publishedOnly is true, a form must be marked as 'published' to be included in the list

Parameters:

published -

Returns:

List of forms

Throws:

APIException

getForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getForms(boolean publishedOnly,
                                                            boolean includeRetired)
                              throws APIException

Deprecated. use getAllForms() or getPublishedForms() or getForms(String, Boolean, Collection, Boolean, Collection, Collection)

Get all forms. If publishedOnly is true, a form must be marked as 'published' to be included in the list. If includeRetired is true 'retired' must be set to false to be include in the list

Parameters:

publishedOnly -

includeRetired -

Returns:

Throws:

APIException

updateForm

@Authorized(value="Manage Forms")
void updateForm(Form form)
                throws APIException

Deprecated. use saveForm(Form)

Save changes to form

Parameters:

form -

Throws:

APIException

duplicateForm

@Authorized(value="Manage Forms")
Form duplicateForm(Form form)
                   throws APIException

Duplicate this form and form_fields associated with this form

Parameters:

form -

Returns:

New duplicated form

Throws:

APIException

retireForm

@Authorized(value="Manage Forms")
void retireForm(Form form,
                                java.lang.String reason)
                throws APIException

Retires the Form, leaving it in the database, but removing it from data entry screens

Parameters:

form - the Form to retire

reason - the retiredReason to set

Throws:

APIException

unretireForm

@Authorized(value="Manage Forms")
void unretireForm(Form form)
                  throws APIException

Unretires a Form that had previous been retired.

Parameters:

form - the Form to revive

Throws:

APIException

purgeForm

@Authorized(value="Manage Forms")
void purgeForm(Form form)
               throws APIException

Completely remove a Form from the database. This is not reversible. It will fail if this form has already been used to create Encounters

Parameters:

form -

Throws:

APIException

purgeForm

@Authorized(value="Manage Forms")
void purgeForm(Form form,
                               boolean cascade)
               throws APIException

Completely remove a Form from the database. This is not reversible. !! WARNING: Calling this method with cascade=true can be very destructive !!

Parameters:

form -

cascade - whether or not to cascade delete all dependent objects (including encounters!)

Throws:

APIException

deleteForm

@Authorized(value="Manage Forms")
void deleteForm(Form form)
                throws APIException

Deprecated. use purgeForm(Form)

Delete form from database. This is included for troubleshooting and low-level system administration. Ideally, this method should never be called — Forms should be retired and not deleted altogether (since many foreign key constraints depend on forms, deleting a form would require deleting all traces, and any historical trail would be lost). This method only clears form roles and attempts to delete the form record. If the form has been included in any other parts of the database (through a foreign key), the attempt to delete the form will violate foreign key constraints and fail.

Parameters:

form -

Throws:

APIException

getFieldTypes

@Authorized(value="View Field Types")
@Transactional(readOnly=true)
java.util.List<FieldType> getFieldTypes()
                                        throws APIException

Deprecated. use getAllFieldTypes()

Throws:

APIException

getAllFieldTypes

@Authorized(value="View Field Types")
@Transactional(readOnly=true)
java.util.List<FieldType> getAllFieldTypes()
                                           throws APIException

Get all field types in the database including the retired ones

Returns:

list of all field types

Throws:

APIException

getAllFieldTypes

@Authorized(value="View Field Types")
@Transactional(readOnly=true)
java.util.List<FieldType> getAllFieldTypes(boolean includeRetired)
                                           throws APIException

Get all field types in the database with or without retired ones

Parameters:

includeRetired - true/false whether to include the retired field types

Returns:

list of all field types

Throws:

APIException

getFieldType

@Transactional(readOnly=true)
@Authorized(value="View Field Types")
FieldType getFieldType(java.lang.Integer fieldTypeId)
                       throws APIException

Get fieldType by internal identifier

Parameters:

fieldType - id to get

Returns:

fieldType with given internal identifier

Throws:

APIException

getForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getForms()
                              throws APIException

Deprecated. use getAllForms()

Throws:

APIException

getForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.Set<Form> getForms(Concept c)
                             throws APIException

Deprecated. use getFormsContainingConcept(Concept)

Throws:

APIException

getFormsContainingConcept

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> getFormsContainingConcept(Concept concept)
                                               throws APIException

Returns all forms that contain the given concept as a field in their schema. (includes retired forms)

Parameters:

concept - the concept to search for in forms

Returns:

forms containing the specified concept in their schema

Throws:

APIException

getFormFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<FormField> getFormFields(Form form)
                                        throws APIException

Deprecated. use Form.getFormFields()

Throws:

APIException

getAllFormFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<FormField> getAllFormFields()
                                           throws APIException

Returns all FormFields in the database

Returns:

all FormFields in the database

Throws:

APIException

findFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Field> findFields(java.lang.String searchPhrase)
                                 throws APIException

Deprecated. use getFields(String)

Returns:

list of fields in the db matching part of search term

Throws:

APIException

getFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Field> getFields(java.lang.String fuzzySearchPhrase)
                                throws APIException

Find all Fields whose names are similar to or contain the given phrase. (The exact similarity algorithm is unspecified.) (includes retired fields)

Parameters:

fuzzySearchPhrase -

Returns:

Fields with names similar to or containing the given phrase

Throws:

APIException

findFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Field> findFields(Concept concept)
                                 throws APIException

Deprecated. use getFieldsByConcept(Concept)

Throws:

APIException

getFieldsByConcept

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Field> getFieldsByConcept(Concept concept)
                                         throws APIException

Finds all Fields that point to the given concept, including retired ones.

Parameters:

concept - the concept to search for in the Field table

Returns:

fields that point to the given concept

Throws:

APIException

getAllFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Field> getAllFields()
                                   throws APIException

Fetches all Fields in the database, including retired ones

Returns:

all Fields

Throws:

APIException

getAllFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Field> getAllFields(boolean includeRetired)
                                   throws APIException

Fetches all Fields in the database, possibly including retired ones

Parameters:

includeRetired - whether or not to include retired Fields

Returns:

all Fields

Throws:

APIException

getFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Field> getFields(java.util.Collection<Form> forms,
                                                              java.util.Collection<FieldType> fieldTypes,
                                                              java.util.Collection<Concept> concepts,
                                                              java.util.Collection<java.lang.String> tableNames,
                                                              java.util.Collection<java.lang.String> attributeNames,
                                                              java.lang.Boolean selectMultiple,
                                                              java.util.Collection<FieldAnswer> containsAllAnswers,
                                                              java.util.Collection<FieldAnswer> containsAnyAnswer,
                                                              java.lang.Boolean retired)
                                throws APIException

Returns all Fields that match these (nullable) criteria

Parameters:

forms - on any of these Forms

fieldTypes - having any of these FieldTypes

concepts - for any of these Concepts

tableNames - for any of these table names

attributeNames - for any of these attribute names

selectMultiple - whether to return only select-multi fields

containsAllAnswers - fields with all the following answers

containsAnyAnswer - fields with any of the following answers

retired - only retired/unretired fields

Returns:

all Fields matching the given criteria

Throws:

APIException

getFields

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Field> getFields()
                                throws APIException

Deprecated. use getAllFields()

Throws:

APIException

getField

@Transactional(readOnly=true)
@Authorized(value="View Forms")
Field getField(java.lang.Integer fieldId)
               throws APIException

Gets a Field by internal database id

Parameters:

fieldId - the id of the Field to fetch

Returns:

the Field with the given id

Throws:

APIException

saveField

@Authorized(value="Manage Forms")
Field saveField(Field field)
                throws APIException

Creates or updates the given Field

Parameters:

field - the Field to save

Returns:

the Field that was saved

Throws:

APIException

createField

@Authorized(value="Manage Forms")
void createField(Field field)
                 throws APIException

Deprecated. use saveField(Field)

Throws:

APIException

updateField

@Authorized(value="Manage Forms")
void updateField(Field field)
                 throws APIException

Deprecated. use saveField(Field)

Throws:

APIException

purgeField

@Authorized(value="Manage Forms")
void purgeField(Field field)
                throws APIException

Completely removes a Field from the database. Not reversible.

Parameters:

field - the Field to purge

Throws:

APIException

purgeField

@Authorized(value="Manage Forms")
void purgeField(Field field,
                                boolean cascade)
                throws APIException

Completely removes a Field from the database. Not reversible. !! WARNING: calling this with cascade=true can be very destructive !!

Parameters:

field - the Field to purge

cascade - whether to cascade delete all FormFields pointing to this field

Throws:

APIException

deleteField

@Authorized(value="Manage Forms")
void deleteField(Field field)
                 throws APIException

Deprecated. use purgeField(Field)

Throws:

APIException

getFormField

@Transactional(readOnly=true)
@Authorized(value="View Forms")
FormField getFormField(java.lang.Integer formFieldId)
                       throws APIException

Gets a FormField by internal database id

Parameters:

fieldId - the internal id to search on

Returns:

the FormField with the given id

Throws:

APIException

getFormField

@Transactional(readOnly=true)
@Authorized(value="View Forms")
FormField getFormField(Form form,
                                                     Concept concept)
                       throws APIException

Finds the FormField defined for this form/concept combination Calls #getFormField(Form, Concept, Collection) with an empty ignore list and with force set to false

Parameters:

form - Form that this concept was found on

concept - (question) on this form that is being requested

Returns:

Formfield for this concept on this form

Throws:

APIException

See Also:

#getFormField(Form, Concept, Collection)}

getFormField

@Transactional(readOnly=true)
@Authorized(value="View Forms")
FormField getFormField(Form form,
                                                     Concept concept,
                                                     java.util.Collection<FormField> ignoreFormFields,
                                                     boolean force)
                       throws APIException

Finds the FormField defined for this form/concept combination while discounting any form field found in the ignoreFormFields collection This method was added when needing to relate observations to form fields during a display. The use case would be that you know a Concept for a obs, which was defined on a form (via a formField). You can relate the formFields to Concepts easily enough, but if a Form reuses a Concept in two separate FormFields you don't want to only associate that first formField with that concept. So, keep a running list of formFields you've seen and pass them back in here to rule them out.

Parameters:

form - Form that this concept was found on

concept - Concept (question) on this form that is being requested

ignoreFormFields - FormFields to ignore (aka already seen formfields)

force - if true and there are zero matches because all formFields were ignored (because of ignoreFormFields) than the first result is returned

Returns:

Formfield for this concept on this form

Throws:

APIException

saveFormField

@Authorized(value="Manage Forms")
FormField saveFormField(FormField formField)
                        throws APIException

Creates or updates the given FormField

Parameters:

formField - the FormField to save

Returns:

the formField that was just saved

Throws:

APIException

createFormField

@Authorized(value="Manage Forms")
void createFormField(FormField formField)
                     throws APIException

Deprecated. use saveFormField(FormField)

Throws:

APIException

updateFormField

@Authorized(value="Manage Forms")
void updateFormField(FormField formField)
                     throws APIException

Deprecated. use saveFormField(FormField)

Throws:

APIException

purgeFormField

@Authorized(value="Manage Forms")
void purgeFormField(FormField formField)
                    throws APIException

Completely removes the given FormField from the database. This is not reversible

Parameters:

formField - the FormField to purge

Throws:

APIException

deleteFormField

@Authorized(value="Manage Forms")
void deleteFormField(FormField formField)
                     throws APIException

Deprecated. use purgeFormField(FormField)

Throws:

APIException

findForms

@Transactional(readOnly=true)
@Authorized(value="View Forms")
java.util.List<Form> findForms(java.lang.String text,
                                                             boolean includeUnpublished,
                                                             boolean includeRetired)

Deprecated. use getForms(String, Boolean, Collection, Boolean, Collection, Collection)

See Also:

getForms(String, Boolean, Collection, Boolean, Collection, Collection)

retireField

@Authorized(value="Manage Forms")
Field retireField(Field field)
                  throws APIException

Retires field

Parameters:

field - the Field to retire

Returns:

the Field that was retired

Throws:

APIException

unretireField

@Authorized(value="Manage Forms")
Field unretireField(Field field)
                    throws APIException

Unretires field

Parameters:

field - the Field to unretire

Returns:

the Field that was unretired

Throws:

APIException

saveFieldType

@Authorized(value="Manage Field Types")
FieldType saveFieldType(FieldType fieldType)
                        throws APIException

Saves the given field type to the database

Parameters:

fieldType - the field type to save

Returns:

the saved field type

Throws:

APIException

purgeFieldType

@Authorized(value="Purge Field Types")
void purgeFieldType(FieldType fieldType)
                    throws APIException

Deletes the given field type from the database. This should not be done. It is preferred to just retired this field type with #retireFieldType(FieldType)

Parameters:

fieldType - the field type to purge

Throws:

APIException