> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connect.fastenhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Component

> The Stitch Web Component has multiple options that can be used to customize the look and feel of the component.

<Warning>
  You are looking at the documentation for an older version of the Stitch SDK

  [Stitch.js (v4)](/stitch/v4/) was recently released and is now the recommended version of the SDK.

  This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.

  v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.

  Older versions of the SDK are in maintenance mode and will no longer receive updates (outside of security fixes).
  Please update your code to use the new version.
</Warning>

```html theme={null}
<fasten-stitch-element
    public-id="public_test_123456324234234"
    external-id="user_12345"
>
</fasten-stitch-element>

<script type="application/javascript">
    const el = document.querySelector('fasten-stitch-element');
    el.addEventListener('eventBus', (event) => console.log(event.detail));
</script>
```

<ParamField path="public-id" type="string" required>
  This must be your API public ID. You can find it in your [Fasten Connect Portal](https://portal.connect.fastenhealth.com).
</ParamField>

<ParamField path="reconnect-org-connection-id" type="string">
  (Optional) Useful when the patient connection credentials are invalid (due to expiration or revocation). Providing this `reconnect-org-connection-id` allows Fasten to reauthenticate the Patient and store their new credentials.
  <Badge color="blue">Reconnect</Badge> When provided, the stitch component will skip the search step and go directly to the reauthentication step for the specified organization connection.
</ParamField>

<ParamField path="external-id" type="string">
  (Optional) An Opaque identifier, used to identify the patient in your system. This value will be returned in the response.
</ParamField>

<ParamField path="search-only" type="boolean">
  (Optional) If set to `true`, the stitch component will only show the search box and will not prompt the patient to verify their email address.
</ParamField>

<ParamField path="search-query" type="string">
  (Optional) Prepopulate the search box with a query.
</ParamField>

<ParamField path="show-splash" type="boolean">
  (Optional) Show a splash page introduces Fasten Connect and displays your privacy policy & terms to the patient before they begin the connection process.

  <Expandable title="example">
    <Card img="https://mintcdn.com/fastenhealth/IYueoKtVsIn7sbVR/images/stitch-splash.png?fit=max&auto=format&n=IYueoKtVsIn7sbVR&q=85&s=6a1d04bc233829aad1058f70b5279392" width="958" height="1660" data-path="images/stitch-splash.png" />
  </Expandable>
</ParamField>

<ParamField path="static-backdrop" type="boolean">
  (Optional) If set to `true`, the stitch component will not close when the user clicks outside of the modal.
  This is useful for cases where you want to keep the modal open until the user explicitly closes it.
</ParamField>

<ParamField path="event-types" type="string">
  (Optional) By default the following standard events are always emitted:

  * `patient.connection_pending`
  * `patient.connection_success`
  * `patient.connection_failed`
  * `widget.complete`.

  If you would like to recieve the optional events listed below, you must set the `event-types` parameter to a comma-separated list of event types.

  * `search.query`: This event is emitted when the patient searches for a healthcare institution in the Fasten Connect catalog.
</ParamField>

# Events

<Note>
  Unlike the previous version of the stitch component, the new version does not support `redirect` mode.
</Note>

The Stitch component will communicate with your frontend application using [JavaScript events](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Events).
Stitch widget will generate a variety of events that you react to via an Event Listener (`addEventListener()`).

```html theme={null}
<script type="application/javascript">
    const el = document.querySelector('fasten-stitch-element');
    el.addEventListener('eventBus', (event) => console.log(event.detail));
</script>
```

### patient.connection\_pending

This event is emitted when the patient has begun the process to connect and the popup window has closed.

```json theme={null}
{
  "api_mode": "live",
  "event_type": "patient.connection_pending",
  "data": {
      "public_id": "",
      "brand_id": "",
      "portal_id": "",
      "endpoint_id": "",

      "external_id": "",
      "external_state": "",

      //only populated when reconnect_org_connection is present
      "org_connection_id": "",
  }
}
```

<ResponseField name="endpoint_id" type="string" required>
  Endpoint Id is a unique identifier for the endpoint that the patient has connected to.
  This value can be used to retrieve metadata about the endpoint (e.g. name, description, endpoint url information, etc.)

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="portal_id" type="string" required>
  Portal Id is a unique identifier for the Portal that the patient has connected to.
  This value can be used to retrieve branding information about the institution

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="brand_id" type="string" required>
  Brand Id is a unique identifier for the Brand that the patient has connected to.
  This value can be used to retrieve branding information about the institution

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="org_connection_id" type="string">
  Organization Connection Id is a unique identifier for the connection between the patient and the organization.

  <Badge color="blue">Reconnect</Badge> Will only be present if the `reconnect-org-connection-id` parameter was provided to the stitch html element.
</ResponseField>

<ResponseField name="external_id" type="string">
  An Opaque identifier, used to identify the patient in your system.
  This value will be only be returned if it was previously provided to the stitch html element.
</ResponseField>

<ResponseField name="external_state" type="string">
  An Opaque identifier, used to identify the connection request.
  This value will be only be returned if it was previously provided to the stitch html element.
</ResponseField>

### patient.connection\_success

This event is emitted when the patient has successfully connected to a single health system.

<Note>
  In most cases you'll want to listen to the `widget.complete` event instead of this one, as it will contain all the successful connections in a single event.
</Note>

```json theme={null}
{
  "api_mode": "live",
  "event_type": "patient.connection_success",
  "data": {
      "org_connection_id": "",
      "endpoint_id": "",
      "brand_id": "",
      "portal_id": "",
      "connection_status": "",
      "platform_type": "",
      "request_id": "",
      "scope": "",
      "consent_expires_at": ""
  }
}
```

<ResponseField name="org_connection_id" type="string" required>
  Organization Connection Id is a unique identifier for the connection between the patient and the organization.
  You must store this value in your system to identify the patient in future API calls.
</ResponseField>

<ResponseField name="endpoint_id" type="string" required>
  Endpoint Id is a unique identifier for the endpoint that the patient has connected to.
  This value can be used to retrieve metadata about the endpoint (e.g. name, description, endpoint url information, etc.)

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="portal_id" type="string" required>
  Portal Id is a unique identifier for the Portal that the patient has connected to.
  This value can be used to retrieve branding information about the institution

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="brand_id" type="string" required>
  Brand Id is a unique identifier for the Brand that the patient has connected to.
  This value can be used to retrieve branding information about the institution

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="connection_status" type="string" required>
  The status of the connection. Possible values are `authorized`, `rejected`.
</ResponseField>

<ResponseField name="platform_type" type="string" required>
  An identifier for the EHR type associated with the connected endpoint.
</ResponseField>

<ResponseField name="request-id" type="string">
  An correlation id. This should be sent with any support ticket queries to the Fasten Connect support team.
</ResponseField>

<ResponseField name="scope" type="string">
  (Optional) The OAuth2 scope that was granted by the patient during the connection process.
  See [https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html)

  Only some EHRs will provide this information. For EHRs that do not provide this information, this field will be omitted.

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field will always be present and will contain the value `patient/*.read`.
</ResponseField>

<ResponseField name="consent_expires_at" type="string">
  (Optional) This will be an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.8) timestamp which will specify when the patient's consent to share data with your application will expire.

  Only some EHRs will provide this information. For EHRs that do not provide this information, this field will be omitted.
</ResponseField>

<ResponseField name="tefca_directory_id" type="string">
  (Optional) The TEFCA Directory ID of the health system that the patient connected to.

  <Badge color="green">TEFCA</Badge> When a health system is connected via TEFCA, this field will be present and will contain the TEFCA Directory ID of the health system.

  Similar to the `brand_id`, this value can be used to retrieve branding information about the institution.
  Prefer the `brand_id` when both values are present.
</ResponseField>

### patient.connection\_failed

This event is emitted when an error occurred while the patient attempted to connect to their health system. The popup window has closed.

```json theme={null}
{
  "api_mode": "live",
  "event_type": "patient.connection_failed",
  "data": {
      "endpoint_id": "",
      "brand_id": "",
      "portal_id": "",
      "connection_status": "",
      "platform_type": "",
      "request_id": "",
      "error": "invalid_request",
      "error_description": "The request is missing a required parameter",
      "error_uri": ""
  }
}
```

<Badge color="green">TEFCA</Badge> This event will not be emitted when connecting in TEFCA mode.

<ResponseField name="endpoint_id" type="string" required>
  Endpoint Id is a unique identifier for the endpoint that the patient has connected to.
  This value can be used to retrieve metadata about the endpoint (e.g. name, description, endpoint url information, etc.)
</ResponseField>

<ResponseField name="portal_id" type="string" required>
  Portal Id is a unique identifier for the Portal that the patient has connected to.
  This value can be used to retrieve branding information about the institution
</ResponseField>

<ResponseField name="brand_id" type="string" required>
  Brand Id is a unique identifier for the Brand that the patient has connected to.
  This value can be used to retrieve branding information about the institution
</ResponseField>

<ResponseField name="connection_status" type="string">
  The status of the connection. Possible values are `authorized`, `rejected`.
</ResponseField>

<ResponseField name="platform_type" type="string">
  An identifier for the EHR type associated with the connected endpoint.
</ResponseField>

<ResponseField name="request_id" type="string" required>
  Every error will have a unique `request_id`. When communicating with the Fasten Health development team, please
  provide the `request_id`, as it will make the debugging process much easier.
</ResponseField>

<ResponseField name="error" type="string" required>
  The `error` parameter will contain a short string representing the error that occurred.

  For errors that occurred on the health system side, the possible values are:

  * `invalid_client`
  * `invalid_grant`
  * `unauthorized_client`
  * `unsupported_grant_type`
  * `invalid_scope`

  For errors that occurred on the Fasten Health side, the possible values are:

  * `fasten_unauthorized_client`
  * `fasten_invalid_request`
  * `fasten_server_error`
  * `fasten_token_exchange`
</ResponseField>

<ResponseField name="error_description" type="string" required>
  The `error_description` parameter can only include ASCII characters, and will be a sentence or two at most describing the circumstance of the error.
</ResponseField>

<ResponseField name="error_uri" type="string">
  The `error_uri` is an optional url parameter that may contain a link to the EHR's API documentation for more information.
</ResponseField>

### widget.complete

This event is emitted when the patient has finished connecting each healthcare institution and has closed the modal.

```json theme={null}
{
  "api_mode": "live",
  "event_type": "widget.complete",
  "data": [{
      "org_connection_id": "",
      "endpoint_id": "",
      "brand_id": "",
      "portal_id": "",
      "connection_status": "",
      "platform_type": "",
      "request_id": ""
  }]
}
```

The `data` field is an array of objects, each object representing a successful connection to a healthcare institution. See `patient.connection_success` for the details of each object.

### widget.config\_error

This event is emitted when the widget is not correctly configured, such as when an invalid public-id is provided, or "tefca" mode is enabled without a paid plan.

```json theme={null}
{
  "api_mode": "test",
  "event_type": "widget.config_error"
}
```

<Note> Ensure that the `public-id` and other required parameters are correctly configured in the widget to avoid this error. </Note>

### search.query (optional)

This event is emitted when the patient searches or a health care institution in the Fasten Connect catalog.
This event is opt-in, and must be configured by setting the `event-types="search.query"` parameter to the stitch Web Component.

```json theme={null}
{
  "api_mode": "live",
  "event_type": "search.query",
  "data": {
      "query": "search term",
      "timestamp": 1674123456,
      "filter": {
        "locations": ["CA"]
      },
      "results": {
        "total": 4
      },
      "external_id": ""
  }
}

```

## Javascript API

The stitch Web Component has a Javascript API that can be used to manipulate the modal popup.

### Methods

#### show()

Shows the modal popup.

```javascript theme={null}
  window.addEventListener('DOMContentLoaded',function () {
    //show the modal using the element selector.
    document.querySelector('fasten-stitch-element').show();
  });
```

#### hide()

Hide the modal popup.

```javascript theme={null}
  window.addEventListener('DOMContentLoaded',function () {
    ...

    //hide the modal using the element selector.
    document.querySelector('fasten-stitch-element').hide();
  });
```

## Styling

Styling the stitch Web Component button is possible using CSS.
You can target the component using the `'fasten-stitch-element'` tag and select internal elements to apply custom styles.

```html theme={null}
  <style>
    fasten-stitch-element > button {
      background-color: green !important
    }
  </style>
```

The `!important` flag may be required to override the default styles.

<Note>
  The `fasten-stitch-element` is made up of a button, modal and iframe.
  As such, you can target the button and modal elements to apply custom styles, but you will not be able to style any content within the iframe.
</Note>

## Customizing Button Text

You can customize the text displayed on the "Share Records" button by adding your desired text between the opening and closing `<fasten-stitch-element>` tags. For example:

```html theme={null}
<fasten-stitch-element
    public-id="public_test_123456324234234"
    external-id="user_12345"
>
    Connect My Health Records
</fasten-stitch-element>
```

In this example, the button will display the text "Connect My Health Records". Replace the text with any message that fits your use case.

<Warning>
  Avoid using overly long text or HTML tags, as this may affect the button's appearance and functionality.
</Warning>

If no text is provided, the default button text will be used.