On this page:

30.14TransactionBuilder 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.

30.14.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

30.14.2Method: withBundle(bundle)

 

This method supports working with an existing transaction bundle.

Inputs:

  • bundle – This is the bundle.

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.withBundle(bundle);
// See below for functions to add things to the transaction

30.14.3Method: 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);

30.14.4Method: update(resource)

 

This method adds a FHIR update 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.id = `123`
patient.name.family = 'Smith';
patient.name.given = 'John';

// Update this patient
transaction.update(patient);

30.14.5Method: patch(resourceId, parameters)

 

This method adds a FHIR patch operation to the transaction.

Inputs:

  • resourceId – This is the resource to patch.
  • parameters – This is the Parameters resource that defines the patch.

Outputs:

  • This method does not return a value.

Example:

var transaction = TransactionBuilder.newTransactionBuilder();

// Create the Parameters resource
let parameters = ResourceBuilder.build('Parameters');
parameters.parameter[0].name = 'operation';
parameters.parameter[0].part[0].name = 'type';
parameters.parameter[0].part[0].valueString = 'add';
parameters.parameter[0].part[1].name = 'path';
parameters.parameter[0].part[1].valueString= 'Patient.name';
parameters.parameter[0].part[2].name = 'name';
parameters.parameter[0].part[2].valueString = 'family';
parameters.parameter[0].part[3].name = 'value';
parameters.parameter[0].part[3].valueString = 'Peterson';

// Patch patient 123
transaction.patch('Patient/123', parameters);

30.14.6Method 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);

30.14.7Method 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);

30.14.8Methods: 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));

30.14.9Fhir.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);