On this page:

20.11TransactionBuilder API

 

The TransactionBuilder is used to construct FHIR transaction bundles (i.e. FHIR Bundle resources with a Bundle.type value of transaction). These are useful for batching a group of related FHIR operations into a single atomic unit.

20.11.1Method: newTransactionBuilder()

 

This method creates a new transaction bundle.

Inputs:

  • This method does not take any arguments.

Outputs:

  • Returns a transaction builder (note that this is not a Bundle object; it is a utility object that is used to build a Bundle object. See below for methods that can be called on the builder.

Example:

var transaction = TransactionBuilder.newTransactionBuilder();
// See below for functions to add things to the transaction

20.11.2Method: create(resource)

 

This method adds a FHIR create operation to the transaction.

Inputs:

  • resource – This is the resource to create.

Outputs:

  • This method does not return a value.

Example:

var transaction = TransactionBuilder.newTransactionBuilder();

// Create a patient
var patient = ResourceBuilder.build('Patient');
patient.name.family = 'Smith';
patient.name.given = 'John';

// Create this patient
transaction.create(patient);

20.11.3Method Chain: createConditional(resource).onToken(parameter, system, value)

 

This method adds a FHIR conditional create operation to the transaction.

Inputs:

  • resource – This is the resource to conditionally create.
  • parameter – The parameter that will be used as the search criteria for determining if the resource already exists. This must be a valid search parameter on the given resource type.
  • system – The system to use in the parameter system.
  • value – The value to use in the parameter value.

Outputs:

  • This method does not return a value.

Example:

var transaction = TransactionBuilder.newTransactionBuilder();

// Create a patient
var patient = ResourceBuilder.build('Patient');
patient.identifier.system = 'http://acme.org/mrns';
patient.identifier.value = '837646';
patient.name.family = 'Smith';
patient.name.given = 'John';

// Create this patient unless a patient already
// exists where Patient?identifier=http://acme.org/mrns|837646
transaction.createConditional(patient).onToken('identifier', patient.identifier.system, patient.identifier.value);

20.11.4Method Chain: updateConditional(resource).onToken(parameter, system, value)

 

This method adds a FHIR conditional update operation to the transaction.

Inputs:

  • resource – This is the resource to conditionally update.
  • parameter – The parameter that will be used as the search criteria for determining if the resource already exists. This must be a valid search parameter on the given resource type.
  • system – The system to use in the parameter system.
  • value – The value to use in the parameter value.

Outputs:

  • This method does not return a value.

Example:

var transaction = TransactionBuilder.newTransactionBuilder();

// Create a patient
var patient = ResourceBuilder.build('Patient');
patient.identifier.system = 'http://acme.org/mrns';
patient.identifier.value = '837646';
patient.name.family = 'Smith';
patient.name.given = 'John';

// Create this patient unless a patient already
// exists where Patient?identifier=http://acme.org/mrns|837646
// in which case that patient will be updated
transaction.updateConditional(patient).onToken('identifier', patient.identifier.system, patient.identifier.value);

20.11.5Methods: toXml(), toXml(prettyPrint), toJson(), toJson(prettyPrint)

 

These methods produce a string serialized representation of the transaction Bundle resource. This can be useful to logging.

Inputs:

  • prettyPrint – If present, this boolean argument specifies whether the output should be "pretty printed", meaning formatted with indentation and new lines for readability by a human. If not specified, the default is true.

Outputs:

  • Returns the raw serialized Bundle resource as a string.

Example:

// Create a transaction
var patient = ResourceBuilder.build('Patient');
patient.identifier[0].system = 'http://acme.org/mrns';
patient.identifier[0].value = '123';
var transaction = TransactionBuilder.newTransactionBuilder();
transaction.create(patient);

// Log the generated bundle
Log.info('Transaction bundle:\n' + transaction.toJson(true));

20.11.6Fhir.transaction(transaction)

 

This method applies the operations in your transaction on your persistence module.

Inputs:

  • transaction – your TransactionBuilder object.

Outputs:

  • Applies operations in your transaction bundle on persistence.
  • Returns nothing.

Example:

// Create a transaction
var patient = ResourceBuilder.build('Patient');
patient.identifier[0].system = 'http://acme.org/mrns';
patient.identifier[0].value = '123';
var transaction = TransactionBuilder.newTransactionBuilder();
transaction.create(patient);

// persist the resources in the transaction bundle
Fhir.transaction(transaction);