Skip to main content

Bot Execute

Invoke a Medplum Bot using the custom $execute operation.

If you're not familiar with Medplum Bots, you may want to review Bot Basics documentation first.

Invoke a bot by ID

Invoke a bot by ID when you know the Bot's ID in advance.

Finding your Bot Id

You can find the id of your Bot by clicking on the Details tab of the Bot resource. In this example, it is 43ac3060-ff20-49e8-9682-bf91ab3a5191

Find your Bot ID

Using POST

POST [base]/Bot/[id]/$execute

Examples

The MedplumClient TypeScript class provides a executeBot convenience method

const result = await medplum.executeBot(id, { input: { foo: 'bar' } });
console.log(result);

Using GET

Query parameters will be passed to the bot as type Record<string, string> (see Content Types below)

GET [base]/Bot/[id]/$execute?params
const getResult = await medplum.get(medplum.fhirUrl('Bot', id, '$execute').toString() + '?foo=bar');
console.log(getResult);

Invoke a bot by identifier

Sometimes you may not know the Medplum Bot ID in advance. In that case, you can invoke a Bot by Identifier.

This is also useful when the same conceptual bot exists in multiple Medplum projects. Each bot will have a different ID, but they can all have the same identifier.

Using POST

POST [base]/Bot/$execute?identifier=[system]|[code]

Examples

The MedplumClient executeBot convenience method supports both id: string and identifier: Identifier:

const result = await medplum.executeBot(
{
system: 'https://example.com/bots',
value: '1234',
},
{
foo: 'bar',
}
);
console.log(result);

Using GET

Query parameters will be passed to the bot as type Record<string, string> (see Content Types below)

GET [base]/Bot/$execute?identifier=[system]|[code]&params
const getResult = await medplum.get(
medplum.fhirUrl('Bot', '$execute').toString() + '?identifier=https://example.com/bots|1234&foo=bar'
);
console.log(getResult);

Content Types

Medplum Bots support a variety of input content types. Specify the input content type using the standard Content-Type HTTP header, or as an optional parameter to MedplumClient.executeBot().

Content-Typetypeof event.inputDescription
text/plainstring<INPUT_DATA> is parsed as plaintext string
application/jsonRecord<string, any><INPUT_DATA> is parsed as JSON-encoded object
application/x-www-form-urlencoded Record<string, string><INPUT_DATA> is parsed as URL-encoded string, resulting in a key/value map
application/fhir+jsonResource<INPUT_DATA> is parsed as a FHIR Resource encoded as JSON
x-application/hl7-v2+er7HL7Message<INPUT_DATA> is a string that should be parsed as a pipe-delimited HL7v2 message. HL7v2 is a common text-based message protocol used in legacy healthcare systems

The input data that will be parsed according to CONTENT_TYPE and passed into your Bot as event.input.